Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
pod::Prima::Window(3) User Contributed Perl Documentationpod::Prima::Window(3)

NAME
       Prima::Window - top-level window	management

SYNOPSIS
	  use Prima;
	  use Prima::Application;

	  # this window, when closed, terminated the application
	  my $main = Prima::MainWindow-> new( text => 'Hello world' );

	  # this is a modal window
	  my $dialog = Prima::Dialog->create( size => [	100, 100 ]);
	  my $result = $dialog-> execute;
	  $dialog-> destroy;

	  run Prima;

DESCRIPTION
       Prima::Window is	a descendant of	Prima::Widget class.  It deals with
       top-level windows, the windows that are specially treated by the
       system. Its major difference from Prima::Widget is that instances of
       Prima::Window can only be inferior by the screen, not the other
       windows,	and that the system or window manager add decorations to these
       - usually menus,	buttons	and title bars.	Prima::Window provides methods
       that communicate	with the system	and hint these decorations.

USAGE
       A typical program communicates with the user with aid of	widgets,
       collected upon one or more top-level windows.  Prima::Widget already
       has all functionality required for these	child-parent operations, so
       Prima::Window is	not special in respect of widget grouping and
       relationship.  Its usage	therefore is straightforward:

	  my $w	= Prima::Window-> create(
	      size => [300,300],
	      text => 'Startup window',
	  );

       There are more about Prima::Window in areas, that it is specifically
       designed	to - the system	window management and the dialog execution.

   System window management
       As noted	before,	top-level windows are special for the system, not only
       in their	'look',	but also in 'feel': the	system adds specific functions
       to the windows, aiding the user to navigate through the desktop.	The
       system ofter dictates the size and position for windows,	and some times
       these rules are hard or even impossible to circumvent. This document
       will be long if it would	venture	to describe the	features of different
       window management systems, and the task would be	never accomplished -
       brand new window	managers emerge	every month, and the old change	their
       behavior	in an unpredictable way. The only golden rule is to never rely
       on the behavior of one window manager, and test programs	with at	least
       two.

       The Prima toolkit provides simple access	to buttons, title bar and
       borders of a window. Buttons and	title bar are managed by the
       "::borderIcons" property, and borders by	the "::borderStyle" property.
       These operate with set of predefined constants, "bi::XXX" and
       "bs::XXX", correspondingly. The button constants	can be combined	with
       each other, but not all combinations may	be granted by the system.  The
       same is valid also for the border constant, except that they can	not be
       combined	- the value of "::borderStyle" is one of the integer
       constants.

       There are other hints that the toolkit can set for a window manager.
       The system can be supplied with an icon that a window is	bound to; the
       icon dimensions are much	different, and although	can be requested via
       "sv::XIcon" and "sv::YIcon" system values, the "::icon" property	scales
       the image automatically to the closest system-recognizable dimension.
       The window icon is not shown by the toolkit, it is usually resides in
       the window decorations and sometimes on a task bar, along with the
       window's	name. The system can be	hinted to not reflect the window on
       the task	bar, by	setting	the "::taskListed" property to 0.

       Another issue is	the window positioning.	Usually, if no explicit
       position	was given, the window is positioned automatically by the
       system. The same	is valid for the size.	But some window	managers bend
       it to the extreme - for example,	default	CDE setup force	the user to
       set newly created windows' positions explicitly.	 However, there	is at
       least one point of certainty.  Typically, when the initial size and/or
       position	of a top-level window are expected to be set by	the system,
       the "::originDontCare" and "::sizeDontCare" properties can be set to 1
       during window creation.	If these set, the system is asked to
       size/position a window regarding	its own	windowing policy. The reverse
       is not always true, unfortunately.  Either if these properties set to
       0, or explicit size or positions	are given, the system is hinted	to use
       these values instead, but this does not always happen. Actually,	this
       behavior	is expected by the user	and often does not get even noticed as
       something special. Therefore it is a good practice to test a top-level
       windowing code with several window managers.

       There are different policies about window positioning and sizing; some
       window managers behave best when	the position is	given to the window
       with the	system-dependent decorations. It is hardly can be called a
       good policy, since it is	not possible to	calculate the derived window
       coordinates with	certainty. This	problem	results	in that	it is
       impossible to be	sure about window position and size before these are
       set explicitly.	The only, not much efficient help the toolkit can
       provide is the property pair "::frameOrigin" and	"::frameSize", which
       along with "::origin" and "::size" reflect the position and size	of a
       window, but taking into account the system-dependent decorations.

   Dialog execution
       Method of Prima::Window,	"execute()" brings a window in a modal state
       on top of other toolkit windows,	and returns after the window is
       dismissed in one	or another way.	 This method is	special	as it is an
       implicit	event loop, similar to

	 run Prima;

       code. The event flow is not disrupted, but the windows and widgets that
       do not belong to	the currently executed,	the 'modal' window group can
       not be activated. There can be many modal windows on top	of each	other,
       but only	one is accessible.  As an example a message box	can be
       depicted, a window that prevents	the user to work with the application
       windows until dismissed.	 There can be other message boxes on top of
       each other, preventing the windows below	from operation as well.	 This
       scheme is called	the 'exclusive'	modality.

       The toolkit also	provides the shared modality scheme, where there can
       be several stacks of modal windows, not interfering with	each other.
       Each window stack is distinct and contains its own windows.  An example
       analogy is when several independent applications	run with modal message
       boxes being activated. This scheme, however, can	not be achieved	with
       single execute()-like call without creating interlocking	conditions.
       The shared model	call, "execute_shared()", inserts the window into the
       shared modal stack, activates the window	and returns immediately.

       The both	kinds of modal windows can coexist, but	the exclusive windows
       prevents	the shared from	operation; while there are exclusive windows,
       the shared have same rights as the usual	windows.

       The stacking order for these two	models is slightly different.  A
       window after execute() call is set on top of the	last exclusive modal
       window, or, in other words, is added to the exclusive window stack.
       There can be only one exclusive window stack, but many shared window
       stacks; a window	after execute_shared() call is added to	a shared
       window stack, to	the one	the window's owner belongs to. The shared
       window stacks are rooted	in so-called modal horizons, windows with
       boolean property	"::modalHorizon" set to	"true".	The default horizon is
       "::application".

       A window	in modal state can return to the normal	(non-modal) state by
       calling "end_modal()" method. The window	is then	hidden and disabled,
       and the windows below are accessible to the user. If the	window was in
       the exclusive modal state, the execute()	call is	finished and returns
       the exit	code, the value	of "::modalResult" property. There two
       shortuct	methods	that end modal state, setting "::modalResult" to the
       basic 'ok' and 'not ok' code, correspondingly "ok()" and	"cancel()"
       methods.	Behavior of "cancel()" is identical to when the	user closes
       the modal window	by clicking the	system close button, pressing Escape
       key, or otherwise cancelling the	dialog execution. "ok()" sets
       "::modalResult" to "mb::OK", "cancel()" to "mb::Cancel",
       correspondingly.	 There are more	"mb::XXX" constants, but these have no
       special meaning,	any integer value can be passed. For example,
       "Prima::MsgBox::message"	method uses these constants so the message
       window can return up to four different "mb" codes.

   Menu
       A top-level window can be equipped with a menu bar. Its outlook is
       system-dependent, but can be controlled by the toolkit up to a certain
       level. The "::menuItems"	property, that manages the menu	items of a
       "::menu"	object of Prima::Menu class, arrange the layout	of the menu.
       The syntax of the items-derived properties is described in Prima::Menu,
       but it must be reiterated that menu items contain only hints, not
       requests	for their exact	representation.	The same is valid for the
       color and font properties, "::menuColorIndex" and "::menuFont".

       Only one	menu at	a time can be displayed	in a top-level window,
       although	a window can be	an owner for many menu objects.	The key
       property	is "Prima::Menu::selected" - if	a menu object is selected on a
       widget or a window object, it refers to the default menu	actions,
       which, in case of Prima::Window is being	displayed as menu bar.

       NB: A window can	be an owner for	several	menu objects and still do not
       have a menu bar displayed, if no	menu objects are marked	as selected.

   Prima::Dialog
       Prima::Dialog, a	descendant from	Prima::Window, introduces no new
       functionality. It has its default values	adjusted so the	colors use
       more appropriate	system colors, and hints the system that the outlook
       of a window is to be different, to resemble the system dialogs on
       systems where such are provided.

   Prima::MainWindow
       The class is a simple descendant	of Prima::Window, which	overloads
       "on_destroy" notification and calls "$application->close" inside	it.
       The purpose of declaration of a separate	class for such a trifle
       difference is that many programs	are designed under a paradigm where
       these is	a main window, which is	most 'important' to the	user. As such
       the construct is	used more often	than any other,	it is considered an
       optimization to write

	  Prima::MainWindow-> create( ... )

       rather than

	  Prima::Window-> create( ...,
	     mainWindow	=> 1,
	     onDestroy	=> sub { $::application-> close	}
	  )

       , although these	lines are equivalent.

       Also, the $::main_window	is pointed to a	newly created main window.

       See also	"mainWindow".

API
   Properties
       borderIcons INTEGER
	   Hints the system about window's decorations,	by selecting the
	   combination of "bi::XXX" constants.	The constants are:

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

	   Not all systems respect these hints,	and many systems provide more
	   navigating decoration controls than these.

       borderStyle STYLE
	   Hints the system about window's border style, by selecting one of
	   "bs::XXX" constants.	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 window mode. If selected, the user can
	   resize the window, not only by dragging the window borders with the
	   mouse but by	other system-dependent means. The other	border styles
	   disallow interactive	resizing.

	   Not all systems recognize all these hints, although many recognize
	   interactive resizing	flag.

       effects HASH or undef
	   This	generic	property implements system-specific window effects,
	   not necessarily portable. The format	of the hash is also system-
	   specific. The only portable behavior	here is	that setting the value
	   to "undef" cancels all effects.

	   Example:

	      $window->effects({
		  effect1 => {
		     key1 => $value1,
		     ...
		  },
	      });

	   Currently, the following effects are	implemented:

	   dwm_blur enable => $BOOL, transition_on_maximized =>	$BOOL, mask =>
	   $Prima::Region
	       This effect is implemented only on Win32	version	7 or later,
	       using Win32 API call DwmEnableBlurBehindWindow
	       <http://msdn.microsoft.com/en-
	       us/library/windows/desktop/aa969508>.  See the MS reference for
	       details.

	       To determine whether this effect	is available or	not, use
	       "$::application->get_system_value(sv::DWM)" call. See
	       examples/dwm_blur.pl for	example	of use.

       frameHeight HEIGHT
	   Maintains the height	of a window, including the window decorations.

       frameOrigin X_OFFSET, Y_OFFSET
	   Maintains the left X	and bottom Y boundaries	of a window's
	   decorations relative	to the screen.

       frameSize WIDTH,	HEIGHT
	   Maintains the width and height of a window, including the window
	   decorations.

       frameWidth WIDTH
	   Maintains the width of a window, including the window decorations.

       icon OBJECT
	   Hints the system about an icon, associated with a window.  If
	   OBJECT is "undef", the system-default icon is assumed.

	   See also: "ownerIcon"

       mainWindow BOOLEAN
	   Tells the system that the window is the main	window for the
	   application.	 When dialogs and modal	windows	are not	anchored to
	   any specific	window,	the main window	is used. In this context,
	   anchoring means that	if, for	example, a window spawns a dialog, and
	   then	is minimized or	obscured, and then the user clicks on either
	   window, both	can be brought forward (also in	correct	Z-order) by
	   the system window manager.

       menu OBJECT
	   Manages a Prima::Menu object	associated with	a window.
	   Prima::Window can host many Prima::Menu objects, but	only the one
	   that	is set in "::menu" property will be seen as a menu bar.

	   See also: "Prima::Menu", "menuItems"

       menuColorIndex INDEX, COLOR
	   Maintains eight color properties of a menu, associated with a
	   window. INDEX must be one of	"ci::XXX" constants ( see
	   Prima::Widget, colorIndex section ).

	   See also: "menuItems", "menuFont", "menu"

       menuColor COLOR
	   Basic foreground menu color.

	   See also: "menuItems", "menuColorIndex", "menuFont",	"menu"

       menuBackColor COLOR
	   Basic background menu color.

	   See also: "menuItems", "menuColorIndex", "menuFont",	"menu"

       menuDark3DColor COLOR
	   Color for drawing dark shadings in menus.

	   See also: "menuItems", "menuColorIndex", "menuFont",	"menu"

       menuDisabledColor COLOR
	   Foreground color for	disabled items in menus.

	   See also: "menuItems", "menuColorIndex", "menuFont",	"menu"

       menuDisabledBackColor COLOR
	   Background color for	disabled items in menus.

	   See also: "menuItems", "menuColorIndex", "menuFont",	"menu"

       menuFont	%FONT
	   Maintains the font of a menu, associated with a window.

	   See also: "menuItems", "menuColorIndex", "menu"

       menuHiliteColor COLOR
	   Foreground color for	selected items in menus.

	   See also: "menuItems", "menuColorIndex", "menuFont",	"menu"

       menuHiliteBackColor COLOR
	   Background color for	selected items in menus.

	   See also: "menuItems", "menuColorIndex", "menuFont",	"menu"

       menuItems [ ITEM_LIST ]
	   Manages items of a Prima::Menu object associated with a window.
	   The ITEM_LIST format	is same	as "Prima::AbstractMenu::items"	and is
	   described in	Prima::Menu.

	   See also: "menu", "menuColorIndex", "menuFont"

       menuLight3DColor	COLOR
	   Color for drawing light shadings in menus.

	   See also: "menuItems", "menuColorIndex", "menuFont",	"menu"

       modalHorizon BOOLEAN
	   Reflects if a window	serves as root to the shared modal window
	   stack.  A window with "::modalHorizon" set to 1 in shared modal
	   state groups	its children windows in	a window stack,	separate from
	   other shared	modal stacks. The "::modalHorizon" is therefore	useful
	   only	when several shared modal window stacks	are needed.

	   The property	also serves as an additional grouping factor for
	   widgets and windows.	For example, default keyboard navigation by
	   tab and arrow keys is limited to the	windows	and widgets of a
	   single window stack.

       modalResult INTEGER
	   Maintains a custom integer value, returned by "execute()".
	   Historically	it is one of "mb::XXX" constants, but any integer
	   value can be	used. The most useful "mb::" constants are:

	      mb::OK, mb::Ok
	      mb::Cancel
	      mb::Yes
	      mb::No
	      mb::Abort
	      mb::Retry
	      mb::Ignore
	      mb::Help

	   NB: These constants are defined so they can be bitwise-or'ed, and
	   Prima::MsgBox package uses this feature, where one of its functions
	   parameters is a combination of "mb::" constants.

       onTop BOOLEAN
	   If set, the window is hinted	to stay	on top of all other windows.

	   Default value: 0

       ownerIcon BOOLEAN
	   If 1, the icon is synchronized with the owner's.  Automatically set
	   to 0	if "::icon" property is	explicitly set.	 Default value is 1,
	   so assigning	an icon	to $::application spawns the icon to all
	   windows.

       taskListed BOOLEAN
	   If set to 0,	hints the system against reflecting existence of a
	   window into a system	task bar, or a top-level window	list, or
	   otherwise lower the window's	value before the other windows.	If 1,
	   does	not hint anything.

	   Default value: 1

       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

	   There can be	more or	less, or other window states provided by the
	   system, but these three were	chosen as a 'least common
	   denominator'.  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()".

	   See also: "WindowState"

   Methods
       cancel
	   A standard method to	dismiss	a modal	window with "mb::Cancel"
	   result. The effect of calling this method is	equal to when the user
	   selects a 'close window' action with	system-provided	menu, button
	   or other tool.

	   See also: "ok", "modalResult", "execute", "execute_shared"

       end_modal
	   If a	window is in modal state, the "EndModal" notification is
	   activated.  Then the	window is returned from	the modal state, gets
	   hidden and disabled.	 If the	window was on top in the exclusive
	   modal state,	the last called	"execute()" function finishes.	If the
	   window was not on top in the	exclusive modal	state, the
	   corresponding "execute()" function finishes after all subsequent
	   execute() calls are finished.

       execute INSERT_BEFORE = undef
	   A window is turned to the exclusive modal state and is put on top
	   of non-modal	and shared-modal windows.  By default, if
	   INSERT_BEFORE object	is undef, the window is	also put on top	of
	   other exclusive-modal windows; if INSERT_BEFORE is one of the
	   exclusive-modal windows the window is placed	in queue before	the
	   INSERT_BEFORE window.  The window is	showed and enabled, if
	   necessary, and "Execute" notification is triggered.

	   The function	is returned when a window is dismissed,	or if the
	   system-dependent 'exit'-event is triggered by the user ( the	latter
	   case	falls through all execute() calls and terminates "run Prima;"
	   call, exiting gracefully).

       execute_shared INSERT_BEFORE = undef
	   A window is turned to the shared modal state	and is put on top of
	   non-modal windows in	the stack of its "::modalHorizon". A window
	   with	"::modalHorizon" set to	1 starts its own stack,	independent of
	   all other window stacks.

	   By default, if INSERT_BEFORE	object is undef, the window is also
	   put on top of other shared-modal windows in its stack.  If
	   INSERT_BEFORE is one	of the shared-modal windows in its stack, the
	   window is placed in queue before the	INSERT_BEFORE window.

	   The window is showed	and enabled, if	necessary, and "Execute"
	   notification	is triggered.

	   The function	is returned immediately.

       get_client_handle
	   Returns a system handle for a system	window that is inserted	in
	   top-level windows and covers	all of its area. Is different from
	   "Window::get_handle"	in that	it returns the system handle of	the
	   top-level window itself. In other terms, window returned by this
	   function is a child of the window returned by "Window::get_handle".

	   See also: "get_handle"

       get_default_menu_font
	   Returns the default font for	a Prima::Menu class.

       get_modal
	   Returns one of three	constants, reflecting the modal	state of a
	   window:

	      mt::None
	      mt::Shared
	      mt::Exclusive

	   Value of "mt::None" is 0, so	result of get_modal() can be also
	   treated as a	boolean	value, if only the fact	of modality is needed
	   to check.

       get_modal_window	MODALITY_TYPE =	mt::Exclusive, NEXT = 1
	   Returns a modal window, that	is next	to the given window in the
	   modality chain. MODALITY_TYPE selects the chain, and	can be either
	   "mt::Exclusive" or "mt::Shared". NEXT is a boolean flag, selecting
	   the lookup direction; if it is 1, the 'upper' window	is returned,
	   if 0, the 'lower' one ( in a	simple case when window	A is made
	   modal (executed) after modal	window B, the A	window is the 'upper'
	   one ).

	   If a	window has no immediate	modal relations,  "undef" is returned.

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

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

       ok  A standard method to	dismiss	a modal	window with "mb::OK" result.
	   Typically the effect	of calling this	method is equal	to when	the
	   user	presses	the enter key of a modal window, signaling that	the
	   default action is to	be taken.

	   See also: "cancel", "modalResult", "execute", "execute_shared"

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

   Events
       Activate
	   Triggered when a window is activated	by the user.  Activation mark
	   is usually resides on a window that contains	keyboard focus,	and is
	   usually reflected by	highlighted system decorations.

	   The toolkit does not	provide	standalone activation functions;
	   "select()" call is used instead.

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

	   The toolkit does not	provide	standalone de-activation functions;
	   "deselect()"	call is	used instead.

       EndModal
	   Called before a window leaves modal state.

       Execute
	   Called after	a window enters	modal state.

       SysHandle
	   Same	as in "Widget",	but it addition	to the Widget properties that
	   may trigger the event, the following	"Window" properties can
	   trigger it as well: taskListed, borderIcons,	borderStyle, onTop

       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.

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

SEE ALSO
       Prima, Prima::Object, Prima::Drawable, Prima::Widget.

perl v5.24.1			  2017-03-13		 pod::Prima::Window(3)

NAME | SYNOPSIS | DESCRIPTION | USAGE | API | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pod::Prima::Window&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help