1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the Qt Designer of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Lesser General Public License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Lesser
19 ** General Public License version 2.1 or version 3 as published by the Free
20 ** Software Foundation and appearing in the file LICENSE.LGPLv21 and
21 ** LICENSE.LGPLv3 included in the packaging of this file. Please review the
22 ** following information to ensure the GNU Lesser General Public License
23 ** requirements will be met: https://www.gnu.org/licenses/lgpl.html and
24 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
25 **
26 ** As a special exception, The Qt Company gives you certain additional
27 ** rights. These rights are described in The Qt Company LGPL Exception
28 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
29 **
30 ** GNU General Public License Usage
31 ** Alternatively, this file may be used under the terms of the GNU
32 ** General Public License version 3.0 as published by the Free Software
33 ** Foundation and appearing in the file LICENSE.GPL included in the
34 ** packaging of this file. Please review the following information to
35 ** ensure the GNU General Public License version 3.0 requirements will be
36 ** met: http://www.gnu.org/copyleft/gpl.html.
37 **
38 ** $QT_END_LICENSE$
39 **
40 ****************************************************************************/
41
42 #include "abstractformwindowcursor.h"
43
44 QT_BEGIN_NAMESPACE
45
46 /*!
47 \class QDesignerFormWindowCursorInterface
48
49 \brief The QDesignerFormWindowCursorInterface class allows you to
50 query and modify a form window's widget selection, and in addition
51 modify the properties of all the form's widgets.
52
53 \inmodule QtDesigner
54
55 QDesignerFormWindowCursorInterface is a convenience class that
56 provides an interface to the associated form window's text cursor;
57 it provides a collection of functions that enables you to query a
58 given form window's selection and change the selection's focus
59 according to defined modes (MoveMode) and movements
60 (MoveOperation). You can also use the interface to query the
61 form's widgets and change their properties.
62
63 The interface is not intended to be instantiated directly, but to
64 provide access to the selections and widgets of \QD's current form
65 windows. QDesignerFormWindowInterface always provides an
66 associated cursor interface. The form window for a given widget
67 can be retrieved using the static
68 QDesignerFormWindowInterface::findFormWindow() functions. For
69 example:
70
71 \snippet doc/src/snippets/code/tools_designer_src_lib_sdk_abstractformwindowcursor.cpp 0
72
73 You can retrieve any of \QD's current form windows through
74 \QD's \l {QDesignerFormWindowManagerInterface}{form window
75 manager}.
76
77 Once you have a form window's cursor interface, you can check if
78 the form window has a selection at all using the hasSelection()
79 function. You can query the form window for its total
80 widgetCount() and selectedWidgetCount(). You can retrieve the
81 currently selected widget (or widgets) using the current() or
82 selectedWidget() functions.
83
84 You can retrieve any of the form window's widgets using the
85 widget() function, and check if a widget is selected using the
86 isWidgetSelected() function. You can use the setProperty()
87 function to set the selected widget's properties, and the
88 setWidgetProperty() or resetWidgetProperty() functions to modify
89 the properties of any given widget.
90
91 Finally, you can change the selection by changing the text
92 cursor's position() using the setPosition() and movePosition()
93 functions.
94
95 \sa QDesignerFormWindowInterface, QDesignerFormWindowManagerInterface
96 */
97
98 /*!
99 \enum QDesignerFormWindowCursorInterface::MoveOperation
100
101 This enum describes the types of text cursor operation that can occur in a form window.
102
103 \value NoMove The cursor does not move.
104 \value Start Moves the cursor to the start of the focus chain.
105 \value End Moves the cursor to the end of the focus chain.
106 \value Next Moves the cursor to the next widget in the focus chain.
107 \value Prev Moves the cursor to the previous widget in the focus chain.
108 \value Left The cursor moves to the left.
109 \value Right The cursor moves to the right.
110 \value Up The cursor moves upwards.
111 \value Down The cursor moves downwards.
112 */
113
114 /*!
115 \enum QDesignerFormWindowCursorInterface::MoveMode
116
117 This enum describes the different modes that are used when the text cursor moves.
118
119 \value MoveAnchor The anchor moves with the cursor to its new location.
120 \value KeepAnchor The anchor remains at the cursor's old location.
121 */
122
123 /*!
124 Returns true if the specified \a widget is selected; otherwise
125 returns false.
126 */
isWidgetSelected(QWidget * widget) const127 bool QDesignerFormWindowCursorInterface::isWidgetSelected(QWidget *widget) const
128 {
129 for (int index=0; index<selectedWidgetCount(); ++index) {
130 if (selectedWidget(index) == widget)
131 return true;
132 }
133
134 return false;
135 }
136
137 /*!
138 \fn virtual QDesignerFormWindowCursorInterface::~QDesignerFormWindowCursorInterface()
139
140 Destroys the cursor interface.
141 */
142
143 /*!
144 \fn virtual QDesignerFormWindowInterface *QDesignerFormWindowCursorInterface::formWindow() const
145
146 Returns the form window interface associated with this cursor interface.
147 */
148
149 /*!
150 \fn virtual bool QDesignerFormWindowCursorInterface::movePosition(MoveOperation operation, MoveMode mode)
151
152 Performs the given \a operation on the cursor using the specified
153 \a mode, and returns true if it completed successfully; otherwise
154 returns false.
155
156 \sa position(), setPosition()
157 */
158
159 /*!
160 \fn virtual int QDesignerFormWindowCursorInterface::position() const
161
162 Returns the cursor position.
163
164 \sa setPosition(), movePosition()
165 */
166
167 /*!
168 \fn virtual void QDesignerFormWindowCursorInterface::setPosition(int position, MoveMode mode = MoveAnchor)
169
170 Sets the position of the cursor to the given \a position using the
171 \a mode to specify how it is moved there.
172
173 \sa position(), movePosition()
174 */
175
176 /*!
177 \fn virtual QWidget *QDesignerFormWindowCursorInterface::current() const
178
179 Returns the currently selected widget in the form window.
180
181 \sa selectedWidget()
182 */
183
184 /*!
185 \fn virtual int QDesignerFormWindowCursorInterface::widgetCount() const
186
187 Returns the number of widgets in the form window.
188
189 \sa selectedWidgetCount()
190 */
191
192 /*!
193 \fn virtual QWidget *QDesignerFormWindowCursorInterface::widget(int index) const
194
195 Returns the widget with the given \a index in the list of widgets
196 in the form window.
197
198 \sa selectedWidget()
199 */
200
201 /*!
202 \fn virtual bool QDesignerFormWindowCursorInterface::hasSelection() const
203
204 Returns true if the form window contains a selection; otherwise
205 returns false.
206 */
207
208 /*!
209 \fn virtual int QDesignerFormWindowCursorInterface::selectedWidgetCount() const
210
211 Returns the number of selected widgets in the form window.
212
213 \sa widgetCount()
214 */
215
216 /*!
217 \fn virtual QWidget *QDesignerFormWindowCursorInterface::selectedWidget(int index) const
218
219 Returns the widget with the given \a index in the list of selected
220 widgets.
221
222 \sa current(), widget()
223 */
224
225 /*!
226 \fn virtual void QDesignerFormWindowCursorInterface::setProperty(const QString &name, const QVariant &value)
227
228 Sets the property with the given \a name for the currently
229 selected widget to the specified \a value.
230
231 \sa setWidgetProperty(), resetWidgetProperty()
232 */
233
234 /*!
235 \fn virtual void QDesignerFormWindowCursorInterface::setWidgetProperty(QWidget *widget, const QString &name, const QVariant &value)
236
237 Sets the property with the given \a name for the given \a widget
238 to the specified \a value.
239
240 \sa resetWidgetProperty(), setProperty()
241 */
242
243 /*!
244 \fn virtual void QDesignerFormWindowCursorInterface::resetWidgetProperty(QWidget *widget, const QString &name)
245
246 Resets the property with the given \a name for the specified \a
247 widget to its default value.
248
249 \sa setProperty(), setWidgetProperty()
250 */
251
252 QT_END_NAMESPACE
253