Man Linux: Main Page and Category List

NAME

       Prima::MDI - top-level windows emulation classes

DESCRIPTION

       MDI stands for Multiple Document Interface, and is a Microsoft Windows
       user interface, that consists of multiple non-toplevel windows
       belonging to an application window. The module contains classes that
       provide similar functionality; sub-window widgets realize a set of
       operations, close to those of the real top-level windows, - iconize,
       maximize, cascade etc.

       The basic classes required to use the MDI are "Prima::MDIOwner" and
       "Prima::MDI", which are, correspondingly, sub-window owner class and
       sub-window class. "Prima::MDIWindowOwner" is exactly the same as
       "Prima::MDIOwner" but is a "Prima::Window" descendant: the both owner
       classes are different only in their first ascendants. Their second
       ascendant is "Prima::MDIMethods" package, that contains all the owner
       class functionality.

       Usage of "Prima::MDI" class extends beyond the multi-document paradigm.
       "Prima::DockManager" module uses the class as a base of a dockable
       toolbar window class ( see Prima::DockManager.

SYNOPSIS

               use Prima::MDI;

               my $owner = Prima::MDIWindowOwner-> create();
               my $mdi   = $owner-> insert( 'Prima::MDI');
               $mdi-> client-> insert( 'Prima::Button' => centered => 1 );

Prima::MDI

       Implements MDI window functionality. A subwindow widget consists of a
       titlebar, titlebar buttons, and a client widget. The latter must be
       used as an insertion target for all children widgets.

       A subwindow can be moved and resized, both by mouse and keyboard.
       These functions, along with maximize, minimize, and restore commands
       are accessible via the toolbar-anchored popup menu. The default set of
       commands is as follows:

               Close window              - Ctrl+F4
               Restore window            - Ctrl+F5 or a double click on the titlebar
               Maximize window           - Ctrl+F10 or a double click on the titlebar
               Go to next MDI window     - Ctrl+Tab
               Go to previous MDI window - Ctrl+Shift+Tab
               Invoke popup menu         - Ctrl+Space

       The class mimics API of "Prima::Window" class, and in some extent
       Prima::Window and this page share the same information.

   Properties
       borderIcons INTEGER
           Selects window decorations, which are buttons on titlebar and the
           titlebar itself.  Can be 0 or a combination of the following
           "mbi::XXX" constants, which are supreset of "bi::XXX" constants (
           see "borderIcons" in Prima::Window ) and are interchangeable.

                   mbi::SystemMenu  - system menu button with icon is shown
                   mbi::Minimize    - minimize button
                   mbi::Maximize    - maximize ( and eventual restore )
                   mbi::TitleBar    - window title
                   mbi::Close       - close button
                   mbi::All         - all of the above

           Default value: "mbi::All"

       borderStyle INTEGER
           One of "bs::XXX" constants, selecting the window border style.  The
           constants are:

                   bs::None      - no border
                   bs::Single    - thin border
                   bs::Dialog    - thick border
                   bs::Sizeable  - thick border with interactive resize capabilities

           "bs::Sizeable" is an unique mode. If selected, the user can resize
           the window interactively. The other border styles disallow resizing
           and affect the border width and design only.

           Default value: "bs::Sizeable"

       client OBJECT
           Selects the client widget at runtime. When changing the client, the
           old client children are not reparented to the new client. The
           property cannot be used to set the client during the MDI window
           creation; use "clientClass" and "clientProfile" properties instead.

           When setting new client object, note that is has to be named
           "MDIClient" and the window is automatically destroyed after the
           client is destroyed.

       clientClass STRING
           Assigns client widget class.

           Create-only property.

           Default value: "Prima::Widget"

       clientProfile HASH
           Assigns hash of properties, passed to the client during the
           creation.

           Create-only property.

       dragMode SCALAR
           A three-state variable, which governs the visual feedback style
           when the user moves or resizes a window. If 1, the window is moved
           or resized simultaneously with the user mouse or keyboard actions.
           If 0, a marquee rectangle is drawn, which is moved or resized as
           the user sends the commands; the window is actually positioned and
           / or resized after the dragging session is successfully finished.
           If "undef", the system-dependant dragging style is used. ( See
           "get_system_value" in Prima::Application ).

           The dragging session can be aborted by hitting Esc key or calling
           "sizemove_cancel" method.

           Default value: "undef".

       icon HANDLE
           Selects a custom image to be drawn in the left corner of the
           toolbar.  If 0, the default image ( menu button icon ) is drawn.

           Default value: 0

       iconMin HANDLE
           Selects minimized button image in normal state.

       iconMax HANDLE
           Selects maximized button image in normal state.

       iconClose HANDLE
           Selects close button image in normal state.

       iconRestore HANDLE
           Selects restore button image in normal state.

       iconMinPressed HANDLE
           Selects minimize button image in pressed state.

       iconMaxPressed HANDLE
           Selects maximize button image in pressed state.

       iconClosePressed HANDLE
           Selects close button image in pressed state.

       iconRestorePressed HANDLE
           Selects restore button image in pressed state.

       tileable BOOLEAN
           Selects whether the window is allowed to participate in cascading
           and tiling auto-arrangements, performed correspondingly by
           "cascade" and "tile" methods.  If 0, the window is never positioned
           automatically.

           Default value: 1

       titleHeight INTEGER
           Selects height of the title bar in pixels. If 0, the default system
           value is used.

           Default value: 0

       windowState STATE
           A three-state property, that governs the state of a window.  STATE
           can be one of three "ws::XXX" constants:

                   ws::Normal
                   ws::Minimized
                   ws::Maximized

           The property can be changed either by explicit set-mode call or by
           the user. In either case, a "WindowState" notification is
           triggered.

           The property has three convenience wrappers: "maximize()",
           "minimize()" and "restore()".

           Default value: "ws::Normal"

           See also: "WindowState"

   Methods
       arrange_icons
           Arranges geometrically the minimized sibling MDI windows.

       cascade
           Arranges sibling MDI windows so they form a cascade-like structure:
           the lowest window is expanded to the full owner window inferior
           rectangle, window next to the lowest occupies the inferior
           rectangle of the lowest window, etc.

           Only windows with "tileable" property set to 1 are processed.

       client2frame X1, Y1, X2, Y2
           Returns a rectangle that the window would occupy if its client
           rectangle is assigned to X1, Y1, X2, Y2 rectangle.

       frame2client X1, Y1, X2, Y2
           Returns a rectangle that the window client would occupy if the
           window rectangle is assigned to X1, Y1, X2, Y2 rectangle.

       get_client_rect [ WIDTH, HEIGHT ]
           Returns a rectangle in the window coordinate system that the client
           would occupy if the window extensions are WIDTH and HEIGHT.  If
           WIDTH and HEIGHT are undefined, the current window size is used.

       keyMove
           Initiates window moving session, navigated by the keyboard.

       keySize
           Initiates window resizing session, navigated by the keyboard.

       mdis
           Returns array of sibling MDI windows.

       maximize
           Maximizes window. A shortcut for "windowState(ws::Maximized)".

       minimize
           Minimizes window. A shortcut for "windowState(ws::Minimized)".

       post_action STRING
           Posts an action to the windows; the action is deferred and executed
           in the next message loop. This is used to avoid unnecessary state
           checks when the action-executing code returns. The current
           implementation accepts following string commands: "min", "max",
           "restore", "close".

       repaint_title [ STRING = "title" ]
           Invalidates rectangle on the title bar, corresponding to STRING,
           which can be one of the following:

                   left    - redraw the menu button
                   right   - redraw minimize, maximize, and close buttons
                   title   - redraw the title

       restore
           Restores window to normal state from minimized or maximized state.
           A shortcut for "windowState(ws::Normal)".

       sizemove_cancel
           Cancels active window moving or resizing session and returns the
           window to the state before the session.

       tile
           Arranges sibling MDI windows so they form a grid-like structure,
           where all windows occupy equal space, if possible.

           Only windows with "tileable" property set to 1 are processed.

       xy2part X, Y
           Maps a point in (X,Y) coordinates into a string, corresponding to a
           part of the window: titlebar, button, or part of the border. The
           latter can be returned only if "borderStyle" is set to
           "bs::Sizeable".  The possible return values are:

                   border   - window border; the window is not sizeable
                   client   - client widget
                   caption  - titlebar; the window is not moveable
                   title    - titlebar; the window is movable
                   close    - close button
                   min      - minimize button
                   max      - maximize button
                   restore  - restore button
                   menu     - menu button
                   desktop  - the point does not belong to the window

           In addition, if the window is sizeable, the following constants can
           be returned, indicating part of the border:

                   SizeN    - upper side
                   SizeS    - lower side
                   SizeW    - left side
                   SizeE    - right side
                   SizeSW   - lower left corner
                   SizeNW   - upper left corner
                   SizeSE   - lower right corner
                   SizeNE   - upper right corner

   Events
       Activate
           Triggered when the user activates a window.  Activation mark is
           usually resides on a window that contains keyboard focus.

           The module does not provide the activation function; "select()"
           call is used instead.

       Deactivate
           Triggered when the user deactivates a window.  Window is usually
           marked inactive, when it contains no keyboard focus.

           The module does not provide the de-activation function;
           "deselect()" call is used instead.

       WindowState STATE
           Triggered when window state is changed, either by an explicit
           "windowState()" call, or by the user.  STATE is the new window
           state, one of three "ws::XXX" constants.

Prima::MDIMethods

   Methods
       The package contains several methods for a class that is to be used as
       a MDI windows owner. It is enough to add class inheritance to
       "Prima::MDIMethods" to use the functionality. This step, however, is
       not required for a widget to become a MDI windows owner; the package
       contains helper functions only, which mostly mirror the arrangement
       functions of "Prima::MDI" class.

       mdi_activate
           Repaints window title in all children MDI windows.

       mdis
           Returns array of children MDI windows.

       arrange_icons
           Same as "Prima::MDI::arrange_icons".

       cascade
           Same as "Prima::MDI::cascade".

       tile
           Same as "Prima::MDI::tile".

Prima::MDIOwner

       A predeclared descendant class of "Prima::Widget" and
       "Prima::MDIMethods".

Prima::MDIWindowOwner

       A pre-declared descendant class of "Prima::Window" and
       "Prima::MDIMethods".

AUTHOR

       Dmitry Karasik, <dmitry@karasik.eu.org>.

SEE ALSO

       Prima, Prima::Widget, Prima::Window, Prima::DockManager,
       examples/mdi.pl