2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
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
9 // http://floralicense.org/license/
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.
19 * @file FUiCtrlOverlayPanel.h
20 * @brief This is the header file for the %OverlayPanel class.
22 * This header file contains the declarations of the %OverlayPanel class.
25 #ifndef _FUI_CTRL_OVERLAY_PANEL_H_
26 #define _FUI_CTRL_OVERLAY_PANEL_H_
28 #include <FBaseTypes.h>
29 #include <FGrpCanvas.h>
30 #include <FUiCtrlPanel.h>
32 namespace Tizen { namespace Ui { namespace Controls
36 * @enum OverlayPanelEvaluationOption
38 * Defines the option for evaluating the bounds of an overlay panel.
42 enum OverlayPanelEvaluationOption
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 */
50 * @brief This class is an implementation of %OverlayPanel.
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.
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.
66 * Example: Please refer to the camera preview example of %Tizen::Media::Camera
69 //Sample code for OverlayPanelSample.h
74 class OverlayPanelSample
75 : public Tizen::Ui::Controls::Form
76 , public Tizen::Ui::IActionEventListener
77 , public Tizen::Media::IPlayerEventListener
80 OverlayPanelSample(void);
81 virtual ~OverlayPanelSample(void);
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);
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);
98 static const int ID_BUTTON_OK = 101;
99 Tizen::Ui::Controls::OverlayPanel* __pOverlayPanel;
104 //Sample code for OverlayPanelSample.cpp
106 #include "OverlayPanelSample.h"
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;
114 OverlayPanelSample::OverlayPanelSample(void)
118 OverlayPanelSample::~OverlayPanelSample(void)
123 OverlayPanelSample::Initialize(void)
125 Construct(FORM_STYLE_NORMAL);
130 OverlayPanelSample::OnInitializing(void)
132 // Set bounds of overlay panel
133 FloatRectangle overlayPanelBounds(10, 10, GetClientAreaBounds().width - 20, 500);
136 int isModifiedBounds = false;
137 result r = OverlayPanel::EvaluateBounds(OVERLAY_PANEL_EVAL_OPT_GREATER_THAN, overlayPanelBounds, isModifiedBounds);
139 // Creates an instance of overlay panel
140 __pOverlayPanel = new OverlayPanel();
141 __pOverlayPanel->Construct(overlayPanelBounds);
142 AddControl(__pOverlayPanel);
144 // Gets a background buffer info
145 BufferInfo bufferinfo;
146 __pOverlayPanel->GetBackgroundBufferInfo(bufferinfo);
148 // Gets a video file path (/res/video.mp4)
149 String videoFilePath = App::GetInstance()->GetAppResourcePath() + L"video.mp4";
151 // Creates an instance of Player
152 Tizen::Media::Player* pPlayer;
153 pPlayer = new Player();
154 pPlayer->Construct(*this, &bufferinfo);
155 pPlayer->OpenFile(videoFilePath);
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);
169 OverlayPanelSample::OnTerminating(void)
171 result r = E_SUCCESS;
173 // Deallocates controls
175 delete __pOverlayPanel;
181 OverlayPanelSample::OnActionPerformed(const Tizen::Ui::Control& source, int actionId)
187 __pOverlayPanel->SetRenderSize(FloatDimension(100.0, 100.0));
188 __pOverlayPanel->SetRendererRotation(__pOverlayPanel->ROTATION_270);
196 // IPlayerEventListener implementation
198 OverlayPanelSample::OnPlayerOpened(result r)
204 OverlayPanelSample::OnPlayerEndOfClip(void)
210 OverlayPanelSample::OnPlayerSeekCompleted(result r)
216 OverlayPanelSample::OnPlayerBuffering(int percent)
222 OverlayPanelSample::OnPlayerErrorOccurred(const PlayerErrorReason r)
228 OverlayPanelSample::OnPlayerInterrupted(void)
234 OverlayPanelSample::OnPlayerReleased(void)
241 class _OSP_EXPORT_ OverlayPanel
242 : public Tizen::Ui::Controls::Panel
248 * Defines the various rotation options.
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 */
270 * @enum BufferPixelFormat
272 * Defines the pixel formats.
276 enum BufferPixelFormat
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 */
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.
294 * This destructor overrides Tizen::Base::Object::~Object().
298 virtual ~OverlayPanel(void);
301 * Initializes this instance of %OverlayPanel at the specified rectangle.
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
316 result Construct(const Tizen::Graphics::Rectangle& rect);
319 * Initializes this instance of %OverlayPanel at the specified rectangle.
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
334 result Construct(const Tizen::Graphics::FloatRectangle& rect);
337 * Sets the rotation of the input buffer. @n
341 * @param[in] rotation The rotation
343 void SetRendererRotation(OverlayPanel::Rotation rotation);
347 * Changes the size of the displayed renderer.
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.
353 * @param[in] dim The dimension of the window to draw
357 void SetRendererSize(Tizen::Graphics::Dimension& dim);
360 * Changes the size of the displayed renderer.
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
372 * OverlayPanel* pOverlayPanel = new OverlayPanel();
373 * pOverlayPanel->Construct(Rectangle(100, 250, 300, 300));
374 * AddControl(pOverlayPanel);
377 * result r = pOverlayPanel->SetRenderSize(Dimesion(300, 200));
381 result SetRenderSize(const Tizen::Graphics::Dimension& dim);
384 * Changes the size of the displayed renderer.
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
396 * OverlayPanel* pOverlayPanel = new OverlayPanel();
397 * pOverlayPanel->Construct(FloatRectangle(100.0, 250.0, 300.0, 300.0));
398 * AddControl(pOverlayPanel);
401 * result r = pOverlayPanel->SetRenderSize(FloatDimesion(300.0, 200.0));
405 result SetRenderSize(const Tizen::Graphics::FloatDimension& dim);
408 * Sets the input buffer.
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.
422 result SetInputBuffer(const Tizen::Graphics::Dimension& destDim, const Tizen::Base::ByteBuffer& srcBuffer, const Tizen::Graphics::Dimension& srcDim, BufferPixelFormat srcFormat);
425 * Sets the input buffer.
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.
439 result SetInputBuffer(const Tizen::Graphics::FloatDimension& destDim, const Tizen::Base::ByteBuffer& srcBuffer, const Tizen::Graphics::Dimension& srcDim, BufferPixelFormat srcFormat);
442 * Gets the information of the background buffer.
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.
453 result GetBackgroundBufferInfo(Tizen::Graphics::BufferInfo& info) const;
457 * Sets the aspect ratio of the renderer.
459 * @brief <i> [Deprecated] </i>
460 * @deprecated This method is deprecated because the renderer aspect ratio is not guaranteed any more.
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
466 * @remarks This method has no effects for hardware accelerated GL backend.
469 void SetRendererAspectRatio(bool fix);
473 * Gets the masking color of this control.
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.
480 * @return Always returns Tizen::Graphics::Color(0x00000000)
483 Tizen::Graphics::Color GetMaskingColor(void) const;
486 * Evaluates and returns the valid position and size that are closest to the specified bounds.
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.
506 static result EvaluateBounds(OverlayPanelEvaluationOption option, Tizen::Graphics::Rectangle& rect, bool& modified);
509 * Evaluates and returns the valid position and size that are closest to the specified bounds.
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.
529 static result EvaluateBounds(OverlayPanelEvaluationOption option, Tizen::Graphics::FloatRectangle& rect, bool& modified);
532 * Gets the BufferPixelFormat list for the %OverlayPanel class. @n
533 * Each list item has a Tizen::UI::Controls::OverlayPanel::BufferPixelFormat value.
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
543 static Tizen::Base::Collection::IListT<BufferPixelFormat>* GetSupportedBufferPixelFormatListN(void);
546 * Gets the width unit. @n
547 * Only a multiple of this value can be allowed as the width of an overlay panel.
551 * @return The value of width
553 static int GetWidthUnit(void);
556 * Gets the height unit. @n
557 * Only a multiple of this value can be allowed as the height of an overlay panel.
561 * @return The value of the height
563 static int GetHeightUnit(void);
566 * Gets the maximum count of overlay panel that can be used simultaneously per application.
570 * @return The maximum count of overlay panel that can be used simultaneously per application
572 static int GetMaxCount(void);
576 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
578 OverlayPanel(const OverlayPanel& rhs);
581 // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
583 OverlayPanel& operator =(const OverlayPanel& rhs);
586 }}} // Tizen::Ui::Controls
588 #endif // _FUI_CTRL_OVERLAY_PANEL_H_