1 #ifndef __DALI_TOOLKIT_CONTROL_H__
2 #define __DALI_TOOLKIT_CONTROL_H__
5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
7 // Licensed under the Flora License, Version 1.0 (the License);
8 // you may not use this file except in compliance with the License.
9 // You may obtain a copy of the License at
11 // http://floralicense.org/license/
13 // Unless required by applicable law or agreed to in writing, software
14 // distributed under the License is distributed on an AS IS BASIS,
15 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 // See the License for the specific language governing permissions and
17 // limitations under the License.
21 * @addtogroup CAPI_DALI_FRAMEWORK
26 #include <dali/dali.h>
28 namespace Dali DALI_IMPORT_API
34 //Forward declarations.
39 * Control is the base class for all controls.
40 * The implementation of the control must be supplied; see ControlImpl for more details.
43 class Control : public CustomActor, public ConnectionTrackerInterface
48 static const char* const ACTION_CONTROL_ACTIVATED;
51 static const char* const SIGNAL_KEY_EVENT;
54 * Describes how a control could be resized.
58 Fixed, ///< Size can't grow or shrink.
59 Minimum, ///< Size can grow but shrink up to a minimum level.
60 Maximum, ///< Size can shrink but grow up to a maximum value.
61 Range, ///< Size can grow or shrink between a minimum and a maximum values.
62 Flexible, ///< Size can grow or shrink with no limits.
66 * Describes what a control should do when a contained actor/control exceeds the boundary of the control.
70 Crop, ///< Control's contents will be cropped.
71 Shrink, ///< Control's contents will be shrunk.
72 Scroll ///< Control's contents will be added to a scroll.
76 * Describes the direction to move the keyboard focus towards
78 enum KeyboardFocusNavigationDirection
80 Left, ///< Move keyboard focus towards the left direction
81 Right, ///< Move keyboard focus towards the right direction
82 Up, ///< Move keyboard focus towards the up direction
83 Down ///< Move keyboard focus towards the down direction
89 typedef SignalV2<bool ( Control, const KeyEvent& ) > KeyEventSignalV2;
91 public: // Creation & Destruction
94 * Create a new instance of a Control.
95 * @return A handle to a new Control.
100 * Create an uninitialized Control handle. Only derived versions can be instantiated.
101 * Calling member functions with an uninitialized Dali::Object is not allowed.
106 * Copy constructor. Creates another handle that points to the same real object
108 Control(const Control& uiControl);
111 * Virtual destructor.
112 * Dali::Object derived classes do not contain member data.
119 * Assignment operator. Changes this handle to point to another real object
121 Control& operator=( const Control& handle );
126 * Downcast an Object handle to Control. If handle points to a Control the
127 * downcast produces valid handle. If not the returned handle is left uninitialized.
128 * @param[in] handle Handle to an object
129 * @return handle to a Control or an uninitialized handle
131 static Control DownCast( BaseHandle handle );
134 * Retrieve the Control implementation.
135 * @return The implementation.
137 ControlImpl& GetImplementation();
140 * Retrieve the Control implementation.
141 * @return The implementation.
143 const ControlImpl& GetImplementation() const;
146 * Sets the size policies for the width and height dimensions.
148 * @param[in] widthPolicy Size policy for the width dimension.
149 * @param[in] heightPolicy Size policy for the height dimension.
151 void SetSizePolicy( SizePolicy widthPolicy, SizePolicy heightPolicy );
154 * Retrieves the size policies for the width and height dimensions.
156 * @param[out] widthPolicy Width's size policy.
157 * @param[out] heightPolicy Height's size policy.
159 void GetSizePolicy( SizePolicy& widthPolicy, SizePolicy& heightPolicy ) const;
162 * Sets the minimum size for the control.
164 * @param[in] size The minimum size.
166 void SetMinimumSize( const Vector3& size );
169 * Retrieves the minimum size.
171 * @return The minimum size.
173 const Vector3& GetMinimumSize() const;
176 * Sets the maximum size
178 * @param[in] size The maximum size.
180 void SetMaximumSize( const Vector3& size );
183 * Retrieves the maximum size.
185 * @return The maximum size.
187 const Vector3& GetMaximumSize() const;
190 * Works out the natural size.
192 * Natural size is the control's size with any restriction.
194 * @return The natural size.
196 Vector3 GetNaturalSize();
199 * Works out the control's height for a given width.
201 * @param[in] width The control's width.
203 * @return The control's height for the given width.
205 float GetHeightForWidth( float width );
208 * Works out the control's width for a given height.
210 * @param[in] height The control's height.
212 * @return The control's width for the given height.
214 float GetWidthForHeight( float height );
217 * This sets the control to receive key events. The key event can originate from a virtual or physical keyboard.
218 * @pre The Control has been initialized.
219 * @pre The Control should be on the stage before setting keyboard focus.
220 * @return True if the control has foucs, False otherwise.
222 void SetKeyInputFocus();
225 * Quries whether the control has key input focus.
226 * Note: The control can be set to have the focus and still not receive all the key events if another control has over ridden it.
227 * As the key input focus mechanism works like a stack, the top most control receives all the key events, and passes on the
228 * unhandled events to the controls below in the stack. A control in the stack will regain key input focus when there are no more
229 * controls above it in the focus stack.
230 * To query for the conrol which is on top of the focus stack use Dali::Toolkit::KeyInputFocusManager::GetCurrentKeyboardFocusActor()
231 * @pre The Control has been initialized.
232 * @pre The Control should be on the stage before setting keyboard focus.
234 bool HasKeyInputFocus();
237 * Once an actor is Set to receive key input focus this function is called to stop it receiving key events.
238 * A check is performed to ensure it was previously set, if this check fails then nothing is done.
239 * @pre The Actor has been initialized.
241 void ClearKeyInputFocus();
247 * This signal is emitted when key event is received
248 * A callback of the following type may be connected:
250 * bool YourCallbackName(Control control, const KeyEvent& event);
252 * The return value of True, indicates that the touch event should be consumed.
253 * Otherwise the signal will be emitted on the next sensitive parent of the actor.
254 * @pre The Control has been initialized.
255 * @return The signal to connect to.
257 KeyEventSignalV2& KeyEventSignal();
262 * @copydoc ConnectionTrackerInterface::SignalConnected
264 virtual void SignalConnected( SlotObserver* slotObserver, CallbackBase* callback );
267 * @copydoc ConnectionTrackerInterface::SignalDisconnected
269 virtual void SignalDisconnected( SlotObserver* slotObserver, CallbackBase* callback );
272 * @copydoc ConnectionTrackerInterface::GetConnectionCount
274 virtual std::size_t GetConnectionCount() const;
276 public: // Not intended for application developers
279 * Create an initialised Control.
280 * @param[in] implementation The implementation for this control.
281 * @return A handle to a newly allocated Dali resource.
283 Control(ControlImpl& implementation);
286 * This constructor is used by CustomActor within Dali core to create additional Control handles
287 * using an Internal CustomActor pointer.
288 * @param [in] internal A pointer to a newly allocated Dali resource
290 Control(Dali::Internal::CustomActor* internal);
292 public: // Templates for Deriving Classes
295 * Template to allow deriving controls to DownCast handles to deriving handle classes.
296 * @tparam T The handle class
297 * @tparam I The implementation class
298 * @param[in] handle Handle to an object
299 * @return Handle to a class T or an uninitialized handle.
300 * @see DownCast(BaseHandle)
302 template<typename T, typename I>
303 static T DownCast( BaseHandle handle )
307 CustomActor custom = Dali::CustomActor::DownCast( handle );
310 CustomActorImpl& customImpl = custom.GetImplementation();
312 I* impl = dynamic_cast<I*>(&customImpl);
316 result = T(customImpl.GetOwner());
324 * Template to allow deriving controls to verify whether the Internal::CustomActor* is actually an
325 * implementation of their class.
326 * @tparam I The implementation class
327 * @param[in] internal Pointer to the Internal::CustomActor
330 void VerifyCustomActorPointer(Dali::Internal::CustomActor* internal)
332 // Can have a NULL pointer so we only need to check if the internal implementation is our class
333 // when there is a value.
336 DALI_ASSERT_DEBUG(dynamic_cast<I*>(&CustomActor(internal).GetImplementation()));
342 } // namespace Toolkit
349 #endif // __DALI_TOOLKIT_CONTROL_H__