Window_t Class Reference
Window base class. More...
#include <UTWindow.h>
Public Member Functions | |
| Window_t (WindowController_t *controller, const String_t &title, const Rect_t &normal_mode_content_area_pframe, Window_t *subordinate_to) | |
| virtual | ~Window_t () |
| WindowController_t * | Controller () const |
| virtual void | Show (window_show_mode_t mode=eWINSHOWMODE_normal) |
| void | Activate () |
| void | SetTitle (const String_t &title) |
| const String_t & | Title () const |
| window_show_mode_t | Mode () const |
| void | SetMenu (Menu_t *menu) |
| Menu_t * | Menu () const |
| void | SetRootView (View_t *root_view) |
| View_t * | RemoveRootView () |
| View_t * | RootView () |
| virtual void | RootViewCannotFitOnscreen () |
| const Rect_t & | NormalModeContentAreaPFrame () const |
| const Rect_t & | CurrentContentAreaLBounds () const |
Detailed Description
Non-core library: UTgui
Window base class. This is a root-level window, with appropriate decorations (title bar, etc) for the target OS. When created by application code, this should be a root document window. To floating windows being able to dock into this window, set a Dockable_t view to be the root view of this window, or if appropriate, add one as a child of the root view. To create a TDI container window, add a TDIContainer_t as the root view of this window, or if appropriate, add one as a child of the root view.
A window cannot be created until App_t::Main has been called. Consequently, when the application object has been created, a message should be posted asynchronously to the application controller task, which triggers it to create the first window.
A Dialog_t is not necessarily a Window_t, since on MacOS it may end up being a sliding sheet. TODO: REALLY??? CAN A SHEET BE SHOWN WHILE NOT BLOCKING THE CALLER AND MAINTAINING ATOMIC EVENT TODO: PROCESSING??? To create a floating window, file selector dialog, directory selector dialog, splash screen, or full-screen window, create the appropriate Window_t subclass instead.
Before beginning implementation of any window, see GUI Design for a detailed discussion of the GUI model used and provided by the UTgui library. Avoiding subclassing is especially important so that based on user preferences, a document can be presented in an SDI document window or a TDI child view, which is not even a window at all. This is why even though the UTgui library uses an object-oriented design, the Window_t class's virtual functions are private, instead relying on task notification function registrations.
A window may not be created unless an App_t has been created, though not necessarily started. Every window runs in the thread context of that App_t, which is a subclass of MessageLoop_t.
A window is the root for a hierarchy of View_t objects. In Windows parlance, a view is still a window. In GTK parlance, a view is a GtkContainer and its GtkWidget base class rolled into one. In MacOS Cocoa parlance, a view is an NSView.
It is in the views that actual rendering occurs. A window must contain a single root view, installed by the subclass derived from Window_t. Typically, that single view implements rendering of the entire content of the window (if the window contains no menu or toolbar), or is merely a container for a number of other views. A view can, optionally, contain any number of child views contained within its boundaries. Child views can even cross the edges of their parent, but they will be clipped such that the visible area is constrained to that of the parent.
When the user closes a window, the Window_t object cannot simply be deleted by the UTgui library because then the controller which owns it would be left holding a dangling pointer to it. Therefore, when the user closes a window, it is not actually closed. Instead, a call is made to the window controller's CloseRequested function. The controller can delete the Window_t or present a "Save changes?" dialog to the user and defer or cancel deleting the window, depending on the user's response.
Definition at line 63 of file UTWindow.h.
Constructor & Destructor Documentation
| Window_t::Window_t | ( | WindowController_t * | controller, | |
| const String_t & | title, | |||
| const Rect_t & | normal_mode_content_area_pframe, | |||
| Window_t * | subordinate_to | |||
| ) |
Window constructor, which creates a root-level window. See the Window_t class documentation for further information on how adding appropriate child panes facilitates the SDI or TDI mode selection. Creating a window does not make it visible. Creation of the underlying OS window will be deferred until the Show function is called, which should not be done until setup of the window and its contents has been performed.
See GUI Design for a detailed discussion of the GUI model used and provided by the UTgui library.
In setting the title, unless the title is from a user-selected source with no extraneous information, it is important to take internationalization into account and use a resource string to obtain the title. For example, if the window title is "Tools", the string should be loaded using a resource string ID.
The normal_mode_content_area is applied when the window is not minimized or maximized. This is merely a request, as the window manager is free to move the window in order to ensure that the specified location is actually onscreen. If the position is respected, the content area is the area, in screen coordinates, which is inside of the window frame decoration. The ability to specify this area is useful for roughly specifying a default window position the first time a new application is run by the user, then storing the location when the window is closed as the user's preference. As long as the screen size or theme have not been changed the next time the application has been run, a window constructed at the preferred location is almost guaranteed to be displayed at that preferred location. The normal mode content area will also not be respected if it contradicts the root view's size constraints. Any such correction will not be made until the window's Show function has been called. For first time window positions (before a user preference has been stored), (40,40) is a safe bet.
| virtual Window_t::~Window_t | ( | ) | [virtual] |
Destructor. If the window has been shown, the underlying OS window, all child views, and all underlying OS representations for child views will be destroyed. A window cannot be destroyed until all windows subordinate to it have first been destroyed.
Member Function Documentation
| WindowController_t * Window_t::Controller | ( | ) | const [inline] |
Returns the window's controller.
Definition at line 353 of file UTWindow.h.
| virtual void Window_t::Show | ( | window_show_mode_t | mode = eWINSHOWMODE_normal |
) | [virtual] |
Shows the window, creating the underlying OS components of the window and all of its children. The mode can be normal, minimized, or maximized.
| void Window_t::Activate | ( | ) |
Activates the window, bringing it to the foreground and into focus.
| void Window_t::SetTitle | ( | const String_t & | title | ) |
Sets the window title.
| const String_t & Window_t::Title | ( | ) | const [inline] |
Returns the window title.
Definition at line 360 of file UTWindow.h.
| window_show_mode_t Window_t::Mode | ( | ) | const [inline] |
Returns the normal, minimized, or maximized mode. The mode can only be set when the window is shown. After that, it's up to the user.
Definition at line 367 of file UTWindow.h.
| void Window_t::SetMenu | ( | Menu_t * | menu | ) |
Sets the window menu. The menu can only be set before the window is shown, or to replace an existing window menu. If the window already had a menu, it will be deleted.
| Menu_t * Window_t::Menu | ( | ) | const [inline] |
Returns the window menu.
Definition at line 374 of file UTWindow.h.
| void Window_t::SetRootView | ( | View_t * | root_view | ) |
Sets the root view. Because Window_t takes posession of and responsibility for deleting the root view, it must have been allocated with operator new. If a root view has already been installed, the old root view is deleted. It is possible, depending on the screen size, for the root view to receive an allocated PFrame that is smaller than its minimum size. If this occurs, the framework will automatically install a ViewPort_t to surround the root view, allowing the user to view the entire window content. If some other action needs to be taken for the application to deal with that situation, it can override the RootViewCannotFitOnscreen virtual function. Because windows can be maximized, the root view needs to be able to handle the case where its PFrame is larger than its specified maximum width and/or height.
| View_t* Window_t::RemoveRootView | ( | ) |
Removes the root view. The caller assumes responsibility for deleting the old root view at an appropriate time if one already existed.
| View_t * Window_t::RootView | ( | ) | [inline] |
Returns a pointer to the root view.
Definition at line 381 of file UTWindow.h.
| virtual void Window_t::RootViewCannotFitOnscreen | ( | ) | [virtual] |
Virtual function which, by default, installs a ViewPort_t containing the old root view, so that the window with the ViewPort_t can fit onscreen, and the user can scroll to access all the contents of the root view that was installed by application code. If some other action needs to be taken to correct the fact that the root view cannot fit onscreen, this function can be overridden.
| const Rect_t & Window_t::NormalModeContentAreaPFrame | ( | ) | const [inline] |
Returns the window's content area (the area inside the target platform's window decoration) in screen coordinates, if the window is not minimized or maximized. If the window is minimized or maximized, returns the same as if it was not. Once a window has been created, its size and position can only be changed by the user. The only exception is when view layout changes alter the size constraints such that they are incompatible with the current window size. This area is not just the portion usable for placing views, but also includes any real estate occupied by a menu bar and/or docked windows like toolbars.
Definition at line 388 of file UTWindow.h.
| const Rect_t & Window_t::CurrentContentAreaLBounds | ( | ) | const [inline] |
Returns the window's current content area, in local coordinates, with the upper left corner always being at (0,0). If the window is minimized, returns whatever the last content rect was before it was minimized. This area is not just the portion usable for placing views, but also includes any real estate occupied by a menu bar and/or docked windows like toolbars.
Definition at line 395 of file UTWindow.h.
The documentation for this class was generated from the following file:
- D:/develop/svn/utlib/utlib/trunk/UT/src_UTgui/UTWindow.h
