Adjust the position of the partial Frame
[platform/framework/native/uifw.git] / inc / FUiCtrlOverlayPanel.h
1 //
2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
4 //
5 // Licensed under the Flora License, Version 1.0 (the License);
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
8 //
9 //     http://floralicense.org/license/
10 //
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an AS IS BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
16 //
17
18 /**
19  * @file        FUiCtrlOverlayPanel.h
20  * @brief       This is the header file for the %OverlayPanel class.
21  *
22  * This header file contains the declarations of the %OverlayPanel class.
23  */
24
25 #ifndef _FUI_CTRL_OVERLAY_PANEL_H_
26 #define _FUI_CTRL_OVERLAY_PANEL_H_
27
28 #include <FBaseTypes.h>
29 #include <FGrpCanvas.h>
30 #include <FUiCtrlPanel.h>
31
32 namespace Tizen { namespace Ui { namespace Controls
33 {
34
35 /**
36  * @enum OverlayPanelEvaluationOption
37  *
38  * Defines the option for evaluating the bounds of an overlay panel.
39  *
40  * @since               2.1
41  */
42 enum OverlayPanelEvaluationOption
43 {
44         OVERLAY_PANEL_EVAL_OPT_GREATER_THAN,    /**< The option evaluating the overlay panel bounds and finding the minimum bounds greater than the input bounds */
45         OVERLAY_PANEL_EVAL_OPT_LESS_THAN        /**< The option evaluating the overlay panel bounds and finding the maximum bounds smaller than input bounds */
46 };
47
48 /**
49  * @class       OverlayPanel
50  * @brief       This class is an implementation of %OverlayPanel.
51  *
52  * @since               2.1
53  *
54  * @remarks     The %OverlayPanel control can only be attached to a %Form control by using Tizen::Ui::Container::AddControl method, because of its native
55  *                      characteristics. Since %OverlayPanel inherits a Panel control, it can be used as a container if needed.
56  *
57  * The %OverlayPanel class is an implementation of the %OverlayPanel control.
58  * The %OverlayPanel is a special type of panel which is used to specify area where the developer
59  * can playback video or camera preview. It is called an overlay because it is possible to overlay
60  * other graphics and controls on top of the panel.
61  * The %OverlayPanel consists of two layers, the foreground panel and background buffer which supports
62  * H/W accelerated rendering. Due to the hardware accelerated nature, there is a limitation with an
63  * %OverlayPanel. The Form that houses an %OverlayPanel can only have a black, opaque background.
64  * The overlay panel can manipulate the rotation and the size of input buffer.
65  *
66  * Example: Please refer to the camera preview example of %Tizen::Media::Camera
67  *
68  * @code
69 //Sample code for OverlayPanelSample.h
70 #include <FBase.h>
71 #include <FMedia.h>
72 #include <FUi.h>
73
74 class OverlayPanelSample
75         : public Tizen::Ui::Controls::Form
76         , public Tizen::Ui::IActionEventListener
77         , public Tizen::Media::IPlayerEventListener
78 {
79 public:
80         OverlayPanelSample(void);
81         virtual ~OverlayPanelSample(void);
82
83         bool Initialize(void);
84         virtual result OnInitializing(void);
85         virtual result OnTerminating(void);
86         virtual void OnActionPerformed(const Tizen::Ui::Control& source, int actionId);
87
88         // IPlayerEventListener
89         virtual void OnPlayerOpened(result r);
90         virtual void OnPlayerEndOfClip(void);
91         virtual void OnPlayerSeekCompleted(result r);
92         virtual void OnPlayerBuffering(int percent);
93         virtual void OnPlayerErrorOccurred(const Tizen::Media::PlayerErrorReason r);
94         virtual void OnPlayerInterrupted(void);
95         virtual void OnPlayerReleased(void);
96
97 private:
98         static const int ID_BUTTON_OK = 101;
99         Tizen::Ui::Controls::OverlayPanel* __pOverlayPanel;
100 };
101  *      @endcode
102  *
103  *      @code
104 //Sample code for OverlayPanelSample.cpp
105 #include <FApp.h>
106 #include "OverlayPanelSample.h"
107
108 using namespace Tizen::App;
109 using namespace Tizen::Base;
110 using namespace Tizen::Graphics;
111 using namespace Tizen::Media;
112 using namespace Tizen::Ui::Controls;
113
114 OverlayPanelSample::OverlayPanelSample(void)
115 {
116 }
117
118 OverlayPanelSample::~OverlayPanelSample(void)
119 {
120 }
121
122 bool
123 OverlayPanelSample::Initialize(void)
124 {
125         Construct(FORM_STYLE_NORMAL);
126         return true;
127 }
128
129 result
130 OverlayPanelSample::OnInitializing(void)
131 {
132         // Set bounds of overlay panel
133         FloatRectangle overlayPanelBounds(10, 10, GetClientAreaBounds().width - 20, 500);
134
135         // Evaluate bounds
136         int isModifiedBounds = false;
137         result r = OverlayPanel::EvaluateBounds(OVERLAY_PANEL_EVAL_OPT_GREATER_THAN, overlayPanelBounds, isModifiedBounds);
138
139         // Creates an instance of overlay panel
140         __pOverlayPanel = new OverlayPanel();
141         __pOverlayPanel->Construct(overlayPanelBounds);
142         AddControl(__pOverlayPanel);
143
144         // Gets a background buffer info
145         BufferInfo bufferinfo;
146         __pOverlayPanel->GetBackgroundBufferInfo(bufferinfo);
147
148         // Gets a video file path (/res/video.mp4)
149         String videoFilePath = App::GetInstance()->GetAppResourcePath() + L"video.mp4";
150
151         // Creates an instance of Player
152         Tizen::Media::Player* pPlayer;
153         pPlayer = new Player();
154         pPlayer->Construct(*this, &bufferinfo);
155         pPlayer->OpenFile(videoFilePath);
156         pPlayer->Play();
157
158         Button *pButton = new Button();
159         pButton->Construct(Rectangle(10, 10, 250, 100));
160         pButton->SetText(L"Change Text");
161         pButton->SetActionId(ID_BUTTON_OK);
162         pButton->AddActionEventListener(*this);
163         __pOverlayPanel->AddControl(pButton);
164
165         return r;
166 }
167
168 result
169 OverlayPanelSample::OnTerminating(void)
170 {
171         result r = E_SUCCESS;
172
173         // Deallocates controls
174         delete __pPlayer;
175         delete __pOverlayPanel;
176
177         return r;
178 }
179
180 void
181 OverlayPanelSample::OnActionPerformed(const Tizen::Ui::Control& source, int actionId)
182 {
183         switch(actionId)
184         {
185         case ID_BUTTON_OK:
186                 {
187                         __pOverlayPanel->SetRenderSize(FloatDimension(100.0, 100.0));
188                         __pOverlayPanel->SetRendererRotation(__pOverlayPanel->ROTATION_270);
189                 }
190                 break;
191         default:
192                 break;
193         }
194 }
195
196 // IPlayerEventListener implementation
197 void
198 OverlayPanelSample::OnPlayerOpened(result r)
199 {
200         // ....
201 }
202
203 void
204 OverlayPanelSample::OnPlayerEndOfClip(void)
205 {
206         // ....
207 }
208
209 void
210 OverlayPanelSample::OnPlayerSeekCompleted(result r)
211 {
212         // ....
213 }
214
215 void
216 OverlayPanelSample::OnPlayerBuffering(int percent)
217 {
218         // ....
219 }
220
221 void
222 OverlayPanelSample::OnPlayerErrorOccurred(const PlayerErrorReason r)
223 {
224         // ....
225 }
226
227 void
228 OverlayPanelSample::OnPlayerInterrupted(void)
229 {
230         // ....
231 }
232
233 void
234 OverlayPanelSample::OnPlayerReleased(void)
235 {
236         // ....
237 }
238  * @endcode
239  */
240
241 class _OSP_EXPORT_ OverlayPanel
242         : public Tizen::Ui::Controls::Panel
243 {
244 public:
245         /**
246          * @enum   Rotation
247          *
248          * Defines the various rotation options.
249          *
250          * @since               2.1
251          */
252         enum Rotation
253         {
254                 ROTATION_NONE,          /**<  No rotation*/
255                 ROTATION_90,            /**<  The 90 degree rotation */
256                 ROTATION_180,           /**< The 180 degree rotation */
257                 ROTATION_270,           /**< The 270 degree rotation */
258                 ROTATION_NONE_LR,       /**< The horizontal mirroring */
259                 ROTATION_NONE_UD,       /**< The vertical mirroring */
260                 ROTATION_90_LR,         /**< The 90 degree rotation with horizontal mirroring */
261                 ROTATION_90_UD,         /**< The 90 degree rotation with vertical mirroring */
262                 ROTATION_180_LR,        /**< The 180 degree rotation with horizontal mirroring */
263                 ROTATION_180_UD,        /**< The 180 degree rotation with vertical mirroring */
264                 ROTATION_270_LR,        /**< The 270 degree rotation with horizontal mirroring */
265                 ROTATION_270_UD,        /**< The 270 degree rotation with vertical mirroring */
266                 ROTATION_MAX
267         };
268
269         /**
270          * @enum  BufferPixelFormat
271          *
272          * Defines the pixel formats.
273          *
274          * @since               2.1
275          */
276         enum BufferPixelFormat
277         {
278                 BUFFER_PIXEL_FORMAT_ARGB8888,                   /**< The ARGB8888 pixel format */
279                 BUFFER_PIXEL_FORMAT_RGB565,                     /**< The RGB565 pixel format */
280                 BUFFER_PIXEL_FORMAT_YCbCr420_PLANAR,    /**< The 8 bit Y plane followed by 8 bit 2 X 2 subsampled U and V planes */
281                 BUFFER_PIXEL_FORMAT_NV12,                               /**< The NV12 pixel format */
282                 BUFFER_PIXEL_FORMAT_UYVY                                /**< The UYVY pixel format */
283         };
284
285         /**
286          * This is the default constructor for this class.
287          * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
288          *
289          * @since               2.1
290          */
291         OverlayPanel(void);
292
293         /**
294          * This destructor overrides Tizen::Base::Object::~Object().
295          *
296          * @since               2.1
297          */
298         virtual ~OverlayPanel(void);
299
300         /**
301          * Initializes this instance of %OverlayPanel at the specified rectangle.
302          *
303          * @since               2.1
304          *
305          * @return              An error code
306          * @param[in]           rect                            The location and size of the %OverlayPanel control @n
307          *                                                              The maximum size is equal to screen size. for example 720 x 1280 on a HD screen, or 480 x 800 on a WVGA screen. @n
308          * @exception           E_SUCCESS               The method is successful.
309          * @exception   E_INVALID_ARG   A specified input parameter @c is invalid.
310          * @exception           E_SYSTEM                A system error has occurred.
311          * @remarks             The size of the control must be within the range defined by the minimum size and the maximum size.
312          *                              To guarantee the size of the render buffer equal to the size of the %OverlayPanel after constructed, checks bounds of @c rect using EvaluateBounds() method before calling this method.
313          * @remarks             Do not use %OverlayPanel in combination with %OverlayRegion. If used, %OverlayPanel may not work as expected.
314          * @see                 %Tizen::Ui::Container
315          */
316         result Construct(const Tizen::Graphics::Rectangle& rect);
317
318         /**
319          * Initializes this instance of %OverlayPanel at the specified rectangle.
320          *
321          * @since               2.1
322          *
323          * @return              An error code
324          * @param[in]           rect                            The location and size of the %OverlayPanel control @n
325          *                                                              The maximum size is equal to screen size. for example 720 x 1280 on a HD screen, or 480 x 800 on a WVGA screen. @n
326          * @exception           E_SUCCESS               The method is successful.
327          * @exception   E_INVALID_ARG   A specified input parameter @c is invalid.
328          * @exception           E_SYSTEM                A system error has occurred.
329          * @remarks             The size of the control must be within the range defined by the minimum size and the maximum size.
330          *                              To guarantee the size of the render buffer equal to the size of the %OverlayPanel after constructed, checks bounds of @c rect using EvaluateBounds() method before calling this method.
331          * @remarks             Do not use %OverlayPanel in combination with %OverlayRegion. If used, %OverlayPanel may not work as expected.
332          * @see                 %Tizen::Ui::Container
333          */
334         result Construct(const Tizen::Graphics::FloatRectangle& rect);
335
336         /**
337          * Sets the rotation of the input buffer. @n
338          *
339          * @since               2.1
340          *
341          * @param[in]   rotation        The rotation
342          */
343         void SetRendererRotation(OverlayPanel::Rotation rotation);
344
345         /**
346          * @if OSPDEPREC
347          * Changes the size of the displayed renderer.
348          *
349          * @brief <i> [Deprecated]  </i>
350          * @deprecated  This method is deprecated. Instead of using this class, use the %OverlayRegion class, that supports video playback and camera preview.
351          * @since                       2.0
352          *
353          * @param[in]   dim     The dimension of the window to draw
354          *
355          * @endif
356          */
357         void SetRendererSize(Tizen::Graphics::Dimension& dim);
358
359         /**
360          * Changes the size of the displayed renderer.
361          *
362          * @since               2.1
363          *
364          * @return      An error code
365          * @param[in]   dim     The dimension of the window to draw
366          * @exception E_SUCCESS                 The method is successful.
367          * @exception E_INVALID_ARG             A specified input parameter is invalid.
368          * @exception E_INVALID_OPERATION       The current state of the instance prohibits the execution of the specified operation.
369          * @remarks     A OverlayPanel becomes displayable only after it has been added to a form.
370          *                      If you want to resize window to draw render buffer, calls this function after the OverlayPanel is added to a %Form control
371          * @code
372          *      OverlayPanel* pOverlayPanel = new OverlayPanel();
373          *      pOverlayPanel->Construct(Rectangle(100, 250, 300, 300));
374          *      AddControl(pOverlayPanel);
375          *
376          *      //...
377          *      result r = pOverlayPanel->SetRenderSize(Dimesion(300, 200));
378          *      //...
379            * @endcode
380          */
381         result SetRenderSize(const Tizen::Graphics::Dimension& dim);
382
383         /**
384          * Changes the size of the displayed renderer.
385          *
386          * @since               2.1
387          *
388          * @return      An error code
389          * @param[in]   dim     The dimension of the window to draw
390          * @exception E_SUCCESS                 The method is successful.
391          * @exception E_INVALID_ARG             A specified input parameter is invalid.
392          * @exception E_INVALID_OPERATION       The current state of the instance prohibits the execution of the specified operation.
393          * @remarks     A OverlayPanel becomes displayable only after it has been added to a form. 
394          *                      If you want to resize window to draw render buffer, calls this function after the OverlayPanel is added to a %Form control
395          * @code
396          *      OverlayPanel* pOverlayPanel = new OverlayPanel();
397          *      pOverlayPanel->Construct(FloatRectangle(100.0, 250.0, 300.0, 300.0));
398          *      AddControl(pOverlayPanel);
399          *
400          *      //...
401          *      result r = pOverlayPanel->SetRenderSize(FloatDimesion(300.0, 200.0));
402          *      //...
403            * @endcode
404          */
405         result SetRenderSize(const Tizen::Graphics::FloatDimension& dim);
406
407         /**
408          * Sets the input buffer.
409          *
410          * @since               2.1
411          *
412          * @param[in]           destDim                                 The dimension of the window to be drawn
413          * @param[in]           srcBuffer                                       The source buffer
414          * @param[in]           srcDim                                  The source dimension
415          * @param[in]           srcFormat                               The pixel format of buffer data
416          * @exception           E_SUCCESS                               The method is successful.
417          * @exception           E_INVALID_ARG                   A specified input parameter is invalid.
418          * @exception           E_SYSTEM                                A system error has occurred.
419          * @exception           E_UNSUPPORTED_FORMAT    The specified pixel format is not supported.
420          * @remarks             Control::Invalidate() methods must be called to properly display the input buffer.
421          */
422         result SetInputBuffer(const Tizen::Graphics::Dimension& destDim, const Tizen::Base::ByteBuffer& srcBuffer, const Tizen::Graphics::Dimension& srcDim, BufferPixelFormat srcFormat);
423
424         /**
425          * Sets the input buffer.
426          *
427          * @since               2.1
428          *
429          * @param[in]           destDim                                 The dimension of the window to be drawn
430          * @param[in]           srcBuffer                                       The source buffer
431          * @param[in]           srcDim                                  The source dimension
432          * @param[in]           srcFormat                               The pixel format of buffer data
433          * @exception           E_SUCCESS                               The method is successful.
434          * @exception           E_INVALID_ARG                   A specified input parameter is invalid.
435          * @exception           E_SYSTEM                                A system error has occurred.
436          * @exception           E_UNSUPPORTED_FORMAT    The specified pixel format is not supported.
437          * @remarks             Control::Invalidate() methods must be called to properly display the input buffer.
438          */
439         result SetInputBuffer(const Tizen::Graphics::FloatDimension& destDim, const Tizen::Base::ByteBuffer& srcBuffer, const Tizen::Graphics::Dimension& srcDim, BufferPixelFormat srcFormat);
440
441         /**
442          * Gets the information of the background buffer.
443          *
444          * @since               2.1
445          *
446          * @return              An error code
447          * @param[out]  info                                    The information of the background buffer
448          * @exception           E_SUCCESS                       The method is successful.
449          * @exception           E_OPERATION_FAILED      The operation has failed.
450          * @remarks             Currently, this method provides buffer information except the pointer of the RGB color buffer. @n
451          *                              Therefore, info.pPixels is always assigned @c null.
452          */
453         result GetBackgroundBufferInfo(Tizen::Graphics::BufferInfo& info) const;
454
455         /**
456          * @if OSPDEPREC
457          * Sets the aspect ratio of the renderer.
458          *
459          * @brief <i> [Deprecated]  </i>
460          * @deprecated  This method is deprecated because the renderer aspect ratio is not guaranteed any more.
461          * @since                       2.0
462          *
463          * @param[in]   fix     Set to @c true if the renderer will display the aspect ratio of the input buffer even if the renderer and input data have
464          *                              different aspect ratios, @n
465          *                              else @c false
466          * @remarks             This method has no effects for hardware accelerated GL backend.
467          * @endif
468          */
469         void SetRendererAspectRatio(bool fix);
470
471         /**
472          * @if OSPDEPREC
473          * Gets the masking color of this control.
474          *
475          * @brief <i> [Deprecated]  </i>
476          * @deprecated  This method is deprecated because masking color does not exist on OverlayPanel any more.
477          * @remarks             Do not call this method. It is not supported.
478          * @since                       2.0
479          *
480          * @return              Always returns Tizen::Graphics::Color(0x00000000)
481          * @endif
482          */
483         Tizen::Graphics::Color GetMaskingColor(void) const;
484
485         /**
486          * Evaluates and returns the valid position and size that are closest to the specified bounds.
487          *
488          * @since               2.1
489          *
490          * @return              An error code
491          * @param[in]           option                          The option for evaluating the bounds of the overlay panel
492          * @param[in, out]      rect                                    An instance of %Tizen::Graphics::Rectangle that represents the validated bounds of %OverlayPanel @n
493          *                                                                      The width and height of the input rectangle must be greater than @c 0.
494          * @param[out]  modified                                A boolean flag that indicates whether the specified @c rectangle is modified
495          * @exception           E_SUCCESS                       The method is successful.
496          * @exception           E_INVALID_ARG                   The specified input parameter @c is invalid.
497          * @exception           E_UNSUPPORTED_OPTION    The specified input parameter @c is not supported.
498          * @exception           E_OPERATION_FAILED              The operation has failed.
499          * @remarks             Due to the hardware accelerated rendering, there are limitations for an overlay panel. @n
500          *                              The hardware capability for an overlay region is checked by using the GetWidthUnit(), GetHeightUnit() and GetMaxCount(). @n
501          *                              If the application runs on multi-screen resolutions, the specified bounds may not meet the hardware limitations of the overlay panel.
502          *                              In such cases, Construct() will return E_INVALID_ARG. @n
503          *                              To prevent this kind of problem, the application must use the OverlayPanel::EvaluateBounds() method to get a validated bounds
504          * @remarks             The specific error code can be accessed using the GetLastResult() method.
505          */
506         static result EvaluateBounds(OverlayPanelEvaluationOption option, Tizen::Graphics::Rectangle& rect, bool& modified);
507
508         /**
509          * Evaluates and returns the valid position and size that are closest to the specified bounds.
510          *
511          * @since               2.1
512          *
513          * @return              An error code
514          * @param[in]           option                          The option for evaluating the bounds of the overlay panel
515          * @param[in, out]      rect                                    An instance of %Tizen::Graphics::FloatRectangle that represents the validated bounds of %OverlayPanel @n
516          *                                                                      The width and height of the input float rectangle must be greater than @c 0.
517          * @param[out]  modified                                A boolean flag that indicates whether the specified @c rectangle is modified
518          * @exception           E_SUCCESS                       The method is successful.
519          * @exception           E_INVALID_ARG                   The specified input parameter @c is invalid.
520          * @exception           E_UNSUPPORTED_OPTION    The specified input parameter @c is not supported.
521          * @exception           E_OPERATION_FAILED              The operation has failed.
522          * @remarks             Due to the hardware accelerated rendering, there are limitations for an overlay panel. @n
523          *                              The hardware capability for an overlay region is checked by using the GetWidthUnit(), GetHeightUnit() and GetMaxCount(). @n
524          *                              If the application runs on multi-screen resolutions, the specified bounds may not meet the hardware limitations of the overlay panel.
525          *                              In such cases, Construct() will return E_INVALID_ARG. @n
526          *                              To prevent this kind of problem, the application must use the OverlayPanel::EvaluateBounds() method to get a validated bounds
527          * @remarks             The specific error code can be accessed using the GetLastResult() method.
528          */
529         static result EvaluateBounds(OverlayPanelEvaluationOption option, Tizen::Graphics::FloatRectangle& rect, bool& modified);
530
531         /**
532          * Gets the BufferPixelFormat list for the %OverlayPanel class. @n
533          * Each list item has a Tizen::UI::Controls::OverlayPanel::BufferPixelFormat value.
534          *
535          * @since               2.1
536          *
537          * @return              A list of the pixel formats supported by the %OverlayPanel class, @n
538          *                              else @c null if no pixel format is supported or an exception occurs
539          * @remark              The specific error code can be accessed using the GetLastResult() method. @n
540          *                              The return value and each item in the list must be deleted by the caller. @n
541          *                              The format list can vary depending on the device. After checking the supported formats using this API, it's better to use a proper pixel format. @n
542          */
543         static Tizen::Base::Collection::IListT<BufferPixelFormat>* GetSupportedBufferPixelFormatListN(void);
544
545         /**
546          * Gets the width unit. @n
547          * Only a multiple of this value can be allowed as the width of an overlay panel.
548          *
549          * @since               2.1
550          *
551          * @return      The value of width
552          */
553         static int GetWidthUnit(void);
554
555         /**
556          * Gets the height unit. @n
557          * Only a multiple of this value can be allowed as the height of an overlay panel.
558          *
559          * @since               2.1
560          *
561          * @return      The value of the height
562          */
563         static int GetHeightUnit(void);
564
565         /**
566          * Gets the maximum count of overlay panel that can be used simultaneously per application.
567          *
568          * @since               2.1
569          *
570          * @return      The maximum count of overlay panel that can be used simultaneously per application
571          */
572         static int GetMaxCount(void);
573
574 private:
575         //
576         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
577         //
578         OverlayPanel(const OverlayPanel& rhs);
579
580         //
581         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
582         //
583         OverlayPanel& operator =(const OverlayPanel& rhs);
584 }; // OverlayPanel
585
586 }}} // Tizen::Ui::Controls
587
588 #endif // _FUI_CTRL_OVERLAY_PANEL_H_
589