forgot to check-in wxGTK wxDC changes

[wxWidgets.git] / contrib / docs / latex / fl / framelayout.tex

%
% automatically generated by HelpGen $Revision$ from
% controlbar.h at 21/Jan/02 21:14:13
%


\section{\class{wxFrameLayout}}\label{wxframelayout}


wxFrameLayout manages containment and docking of control bars,
which can be docked along the top, bottom, right, or left side of the
parent frame.

\wxheading{Derived from}

\helpref{wxEvtHandler}{wxevthandler}

\wxheading{Include files}

<wx/fl/controlbar.h>

\wxheading{Data structures}

\latexignore{\rtfignore{\wxheading{Members}}}


\membersection{wxFrameLayout::wxFrameLayout}\label{wxframelayoutwxframelayout}

\func{}{wxFrameLayout}{\param{wxWindow* }{pParentFrame}, \param{wxWindow* }{pFrameClient = NULL}, \param{bool }{activateNow = TRUE}}

Constructor, taking parent window, the (MDI) client of the parent if there
is one, and flag specifying whether to activate the layout.


\func{}{wxFrameLayout}{\void}

Default constructor, used only for serialization.


\membersection{wxFrameLayout::\destruct{wxFrameLayout}}\label{wxframelayoutdtor}

\func{}{\destruct{wxFrameLayout}}{\void}

Destructor. It does not destroy the bar windows.


\membersection{wxFrameLayout::Activate}\label{wxframelayoutactivate}

\func{void}{Activate}{\void}

Activate can be called after some other layout has been deactivated,
and this one must take over the current contents of the frame window.
Effectively hooks itself to the frame window, re-displays all non-hidden
bar windows and repaints the decorations.


\membersection{wxFrameLayout::AddBar}\label{wxframelayoutaddbar}

\func{void}{AddBar}{\param{wxWindow* }{pBarWnd}, \param{const cbDimInfo\& }{dimInfo}, \param{int }{alignment = FL\_ALIGN\_TOP}, \param{int }{rowNo = 0}, \param{int }{columnPos = 0}, \param{const wxString\& }{name = "bar"}, \param{bool }{spyEvents = FALSE}, \param{int }{state = wxCBAR\_DOCKED\_HORIZONTALLY}}

Adds bar information to the frame layout. The appearance of the layout is not refreshed
immediately; RefreshNow() can be called if necessary.
Notes: the argument pBarWnd can by NULL, resulting in bar decorations to be drawn
around the empty rectangle (filled with default background colour).
Argument dimInfo can be reused for adding any number of bars, since
it is not used directly - instead its members are copied. If the dimensions
handler is present, its instance is shared (reference counted). The dimension
handler should always be allocated on the heap.
pBarWnd is the window to be managed.
dimInfo contains dimension information.
alignment is a value such as FL\_ALIGN\_TOP.
rowNo is the vertical position or row in the pane (if in docked state).
columnPos is the horizontal position within the row in pixels (if in docked state).
name is a name by which the bar can be referred in layout customization dialogs.
If spyEvents is TRUE, input events for the bar should be "spyed" in order
to forward unhandled mouse clicks to the frame layout, for example to enable
easy draggablity of toolbars just by clicking on their interior regions.
For widgets like text/tree control this value should be FALSE,
since there's no certain way to detect  whether the event was actually handled.
state is the initial state, such as wxCBAR\_DOCKED\_HORIZONTALLY,
wxCBAR\_FLOATING, wxCBAR\_HIDDEN.


\membersection{wxFrameLayout::AddPlugin}\label{wxframelayoutaddplugin}

\func{void}{AddPlugin}{\param{wxClassInfo* }{pPlInfo}, \param{int }{paneMask = wxALL\_PANES}}

An advanced methods for plugin configuration    using their
dynamic class information, for example CLASSINFO(pluginClass).
First checks if the plugin of the given class is already "hooked up".
If not, adds it to the top of the plugins chain.


\membersection{wxFrameLayout::AddPluginBefore}\label{wxframelayoutaddpluginbefore}

\func{void}{AddPluginBefore}{\param{wxClassInfo* }{pNextPlInfo}, \param{wxClassInfo* }{pPlInfo}, \param{int }{paneMask = wxALL\_PANES}}

First checks if the plugin of the given class is already hooked.
If so, removes it, and then inserts it into the chain
before the plugin of the class given by pNextPlInfo.
Note: this method is handy in some cases where the order
of the plugin-chain could be important, for example when one plugin overrides
some functionality of another already-hooked plugin,
so that the former plugin should be hooked before the one
whose functionality is being overridden.


\membersection{wxFrameLayout::ApplyBarProperties}\label{wxframelayoutapplybarproperties}

\func{void}{ApplyBarProperties}{\param{cbBarInfo* }{pBar}}

Reflects changes in bar information structure visually.
For example, moves the bar, changes its dimension information,
or changes the pane to which it is docked.


\membersection{wxFrameLayout::CanReparent}\label{wxframelayoutcanreparent}

\func{bool}{CanReparent}{\void}

Returns TRUE if the platform allows reparenting. This may not return TRUE
for all platforms. Reparenting allows control bars to be floated.


\membersection{wxFrameLayout::CaptureEventsForPane}\label{wxframelayoutcaptureeventsforpane}

\func{void}{CaptureEventsForPane}{\param{cbDockPane* }{toPane}}

Called by plugins; also captures the mouse in the parent frame.


\membersection{wxFrameLayout::CaptureEventsForPlugin}\label{wxframelayoutcaptureeventsforplugin}

\func{void}{CaptureEventsForPlugin}{\param{cbPluginBase* }{pPlugin}}

Captures user input events for the given plugin.
Input events are: mouse movement, mouse clicks, keyboard input.


\membersection{wxFrameLayout::CreateCursors}\label{wxframelayoutcreatecursors}

\func{void}{CreateCursors}{\void}

Creates the cursors.


\membersection{wxFrameLayout::CreateUpdatesManager}\label{wxframelayoutcreateupdatesmanager}

\func{cbUpdatesManagerBase*}{CreateUpdatesManager}{\void}

Returns a new cbGCUpdatesMgr object.


\membersection{wxFrameLayout::Deactivate}\label{wxframelayoutdeactivate}

\func{void}{Deactivate}{\void}

Deactivate unhooks itself from frame window, and hides all non-hidden windows.
Note: two frame layouts should not be active at the same time in the
same frame window, since it would cause messy overlapping of bar windows
from both layouts.


\membersection{wxFrameLayout::DestroyBarWindows}\label{wxframelayoutdestroybarwindows}

\func{void}{DestroyBarWindows}{\void}

Destroys the bar windows.


\membersection{wxFrameLayout::DoSetBarState}\label{wxframelayoutdosetbarstate}

\func{void}{DoSetBarState}{\param{cbBarInfo* }{pBar}}

Applies the state to the window objects.


\membersection{wxFrameLayout::EnableFloating}\label{wxframelayoutenablefloating}

\func{void}{EnableFloating}{\param{bool }{enable = TRUE}}

Enables floating behaviour. By default floating of control bars is on.


\membersection{wxFrameLayout::FindBarByName}\label{wxframelayoutfindbarbyname}

\func{cbBarInfo*}{FindBarByName}{\param{const wxString\& }{name}}

Finds the bar in the framelayout, by name.


\membersection{wxFrameLayout::FindBarByWindow}\label{wxframelayoutfindbarbywindow}

\func{cbBarInfo*}{FindBarByWindow}{\param{const wxWindow* }{pWnd}}

Finds the bar in the framelayout, by window.


\membersection{wxFrameLayout::FindPlugin}\label{wxframelayoutfindplugin}

\func{cbPluginBase*}{FindPlugin}{\param{wxClassInfo* }{pPlInfo}}

Finds a plugin with the given class, or returns NULL if a plugin of the given
class is not hooked.


\membersection{wxFrameLayout::FirePluginEvent}\label{wxframelayoutfirepluginevent}

\func{void}{FirePluginEvent}{\param{cbPluginEvent\& }{event}}

This function should be used instead of passing the event to the ProcessEvent method
of the top-level plugin directly. This method checks if events are currently
captured and ensures that plugin-event is routed correctly.


\membersection{wxFrameLayout::ForwardMouseEvent}\label{wxframelayoutforwardmouseevent}

\func{void}{ForwardMouseEvent}{\param{wxMouseEvent\& }{event}, \param{cbDockPane* }{pToPane}, \param{int }{eventType}}

Delegated from "bar-spy".


\membersection{wxFrameLayout::GetBarPane}\label{wxframelayoutgetbarpane}

\func{cbDockPane*}{GetBarPane}{\param{cbBarInfo* }{pBar}}

Returns the pane to which the given bar belongs.


\membersection{wxFrameLayout::GetBars}\label{wxframelayoutgetbars}

\func{BarArrayT\&}{GetBars}{\void}

Gets an array of bars.


\membersection{wxFrameLayout::GetClientHeight}\label{wxframelayoutgetclientheight}

\func{int}{GetClientHeight}{\void}

Returns the client height.


\membersection{wxFrameLayout::GetClientRect}\label{wxframelayoutgetclientrect}

\func{wxRect\&}{GetClientRect}{\void}

Returns the client's rectangle.


\membersection{wxFrameLayout::GetClientWidth}\label{wxframelayoutgetclientwidth}

\func{int}{GetClientWidth}{\void}

Returns the client width.


\membersection{wxFrameLayout::GetFrameClient}\label{wxframelayoutgetframeclient}

\func{wxWindow*}{GetFrameClient}{\void}

Returns the frame client, or NULL if not present.


\membersection{wxFrameLayout::GetPane}\label{wxframelayoutgetpane}

\func{cbDockPane*}{GetPane}{\param{int }{alignment}}

Returns a pane for the given alignment. See pane alignment types.


\membersection{wxFrameLayout::GetPaneProperties}\label{wxframelayoutgetpaneproperties}

\func{void}{GetPaneProperties}{\param{cbCommonPaneProperties\& }{props}, \param{int }{alignment = FL\_ALIGN\_TOP}}

Gets the pane properties for the given alignment.


\membersection{wxFrameLayout::GetPanesArray}\label{wxframelayoutgetpanesarray}

\func{cbDockPane**}{GetPanesArray}{\void}

Returns an array of panes. Used by update managers.


\membersection{wxFrameLayout::GetParentFrame}\label{wxframelayoutgetparentframe}

\func{wxWindow\&}{GetParentFrame}{\void}

Returns the parent frame.


\membersection{wxFrameLayout::GetPrevClientRect}\label{wxframelayoutgetprevclientrect}

\func{wxRect\&}{GetPrevClientRect}{\void}

Returns the previous client window rectangle.


\membersection{wxFrameLayout::GetTopPlugin}\label{wxframelayoutgettopplugin}

\func{cbPluginBase\&}{GetTopPlugin}{\void}

Returns the current top-level plugin (the one that receives events first,
except if input events are currently captured by some other plugin).


\membersection{wxFrameLayout::GetUpdatesManager}\label{wxframelayoutgetupdatesmanager}

\func{cbUpdatesManagerBase\&}{GetUpdatesManager}{\void}

Returns a reference to the updates manager.
Note: in future, the updates manager will become a normal plugin.


\membersection{wxFrameLayout::HasTopPlugin}\label{wxframelayouthastopplugin}

\func{bool}{HasTopPlugin}{\void}

Returns true if there is a top plugin.


\membersection{wxFrameLayout::HideBarWindows}\label{wxframelayouthidebarwindows}

\func{void}{HideBarWindows}{\void}

Hides the bar windows, and also the client window if present.


\membersection{wxFrameLayout::HitTestPane}\label{wxframelayouthittestpane}

\func{bool}{HitTestPane}{\param{cbDockPane* }{pPane}, \param{int }{x}, \param{int }{y}}

Returns TRUE if the position is within the given pane.


\membersection{wxFrameLayout::HitTestPanes}\label{wxframelayouthittestpanes}

\func{cbDockPane*}{HitTestPanes}{\param{const wxRect\& }{rect}, \param{cbDockPane* }{pCurPane}}

Returns the pane for which the rectangle hit test succeeds, giving
preference to the given pane if supplied.


\membersection{wxFrameLayout::HookUpToFrame}\label{wxframelayouthookuptoframe}

\func{void}{HookUpToFrame}{\void}

Hooks the layout up to the frame (pushes the layout onto the
frame's event handler stack).


\membersection{wxFrameLayout::InverseVisibility}\label{wxframelayoutinversevisibility}

\func{void}{InverseVisibility}{\param{cbBarInfo* }{pBar}}

Toggles the bar between visible and hidden.


\membersection{wxFrameLayout::LocateBar}\label{wxframelayoutlocatebar}

\func{bool}{LocateBar}{\param{cbBarInfo* }{pBarInfo}, \param{cbRowInfo** }{ppRow}, \param{cbDockPane** }{ppPane}}

The purpose of this function is unknown.


\membersection{wxFrameLayout::OnActivate}\label{wxframelayoutonactivate}

\func{void}{OnActivate}{\param{wxActivateEvent\& }{event}}

Handles activation events. Currently does nothing.


\membersection{wxFrameLayout::OnEraseBackground}\label{wxframelayoutonerasebackground}

\func{void}{OnEraseBackground}{\param{wxEraseEvent\& }{event}}

Handles background erase events. Currently does nothing.


\membersection{wxFrameLayout::OnIdle}\label{wxframelayoutonidle}

\func{void}{OnIdle}{\param{wxIdleEvent\& }{event}}

Handles idle events.


\membersection{wxFrameLayout::OnKillFocus}\label{wxframelayoutonkillfocus}

\func{void}{OnKillFocus}{\param{wxFocusEvent\& }{event}}

Handles focus kill events. Currently does nothing.


\membersection{wxFrameLayout::OnLButtonDown}\label{wxframelayoutonlbuttondown}

\func{void}{OnLButtonDown}{\param{wxMouseEvent\& }{event}}

Event handler for a left down button event.


\membersection{wxFrameLayout::OnLButtonUp}\label{wxframelayoutonlbuttonup}

\func{void}{OnLButtonUp}{\param{wxMouseEvent\& }{event}}

Event handler for a left button up event.


\membersection{wxFrameLayout::OnLDblClick}\label{wxframelayoutonldblclick}

\func{void}{OnLDblClick}{\param{wxMouseEvent\& }{event}}

Event handler for a left doubleclick button event.


\membersection{wxFrameLayout::OnMouseMove}\label{wxframelayoutonmousemove}

\func{void}{OnMouseMove}{\param{wxMouseEvent\& }{event}}

Event handler for a mouse move event.


\membersection{wxFrameLayout::OnPaint}\label{wxframelayoutonpaint}

\func{void}{OnPaint}{\param{wxPaintEvent\& }{event}}

Handles paint events, calling PaintPane for each pane.


\membersection{wxFrameLayout::OnRButtonDown}\label{wxframelayoutonrbuttondown}

\func{void}{OnRButtonDown}{\param{wxMouseEvent\& }{event}}

Event handler for a right button down event.


\membersection{wxFrameLayout::OnRButtonUp}\label{wxframelayoutonrbuttonup}

\func{void}{OnRButtonUp}{\param{wxMouseEvent\& }{event}}

Event handler for a right button up event.


\membersection{wxFrameLayout::OnSetFocus}\label{wxframelayoutonsetfocus}

\func{void}{OnSetFocus}{\param{wxFocusEvent\& }{event}}

Handles focus set events. Currently does nothing.


\membersection{wxFrameLayout::OnSize}\label{wxframelayoutonsize}

\func{void}{OnSize}{\param{wxSizeEvent\& }{event}}

Event handler for a size event.


\membersection{wxFrameLayout::PopAllPlugins}\label{wxframelayoutpopallplugins}

\func{void}{PopAllPlugins}{\void}

Pop all plugins.


\membersection{wxFrameLayout::PopPlugin}\label{wxframelayoutpopplugin}

\func{void}{PopPlugin}{\void}

Similar to wxWindow's "push/pop-event-handler" methods, execept
that the plugin is deleted upon "popping".


\membersection{wxFrameLayout::PositionClientWindow}\label{wxframelayoutpositionclientwindow}

\func{void}{PositionClientWindow}{\void}

Called to apply the calculated layout to window objects.


\membersection{wxFrameLayout::PositionPanes}\label{wxframelayoutpositionpanes}

\func{void}{PositionPanes}{\void}

Called to apply the calculated layout to window objects.


\membersection{wxFrameLayout::PushDefaultPlugins}\label{wxframelayoutpushdefaultplugins}

\func{void}{PushDefaultPlugins}{\void}

Adds the default plugins. These are cbPaneDrawPlugin, cbRowLayoutPlugin, cbBarDragPlugin,
cbAntiflickerPlugin, cbSimpleCustomizePlugin.
This method is automatically invoked if no plugins were found upon
firing of the first plugin-event, i.e. when wxFrameLayout configures itself.


\membersection{wxFrameLayout::PushPlugin}\label{wxframelayoutpushplugin}

\func{void}{PushPlugin}{\param{cbPluginBase* }{pPugin}}

Similar to wxWindow's "push/pop-event-handler" methods, execept
that the plugin is deleted upon "popping".


\membersection{wxFrameLayout::RecalcLayout}\label{wxframelayoutrecalclayout}

\func{void}{RecalcLayout}{\param{bool }{repositionBarsNow = FALSE}}

Recalculates the layout of panes, and all bars/rows in each pane.


\membersection{wxFrameLayout::RedockBar}\label{wxframelayoutredockbar}

\func{bool}{RedockBar}{\param{cbBarInfo* }{pBar}, \param{const wxRect\& }{shapeInParent}, \param{cbDockPane* }{pToPane = NULL}, \param{bool }{updateNow = TRUE}}

ReddockBar can be used for repositioning existing bars. The given bar is first removed
from the pane it currently belongs to, and inserted into the pane, which "matches"
the given rectangular area. If pToPane is not NULL, the bar is docked to this given pane.
To dock a bar which is floating, use the wxFrameLayout::DockBar method.


\membersection{wxFrameLayout::RefreshNow}\label{wxframelayoutrefreshnow}

\func{void}{RefreshNow}{\param{bool }{recalcLayout = TRUE}}

Recalculates layout and performs on-screen update of all panes.


\membersection{wxFrameLayout::ReleaseEventsFromPane}\label{wxframelayoutreleaseeventsfrompane}

\func{void}{ReleaseEventsFromPane}{\param{cbDockPane* }{fromPane}}

Called by plugins; also releases mouse in the parent frame.


\membersection{wxFrameLayout::ReleaseEventsFromPlugin}\label{wxframelayoutreleaseeventsfromplugin}

\func{void}{ReleaseEventsFromPlugin}{\param{cbPluginBase* }{pPlugin}}

Releases user input events for the given plugin.
Input events are: mouse movement, mouse clicks, keyboard input


\membersection{wxFrameLayout::RemoveBar}\label{wxframelayoutremovebar}

\func{void}{RemoveBar}{\param{cbBarInfo* }{pBar}}

Removes the bar from the layout permanently, and hides its corresponding window if present.


\membersection{wxFrameLayout::RemovePlugin}\label{wxframelayoutremoveplugin}

\func{void}{RemovePlugin}{\param{wxClassInfo* }{pPlInfo}}

Checks if the plugin of the given class is hooked, and removes
it if found.


\membersection{wxFrameLayout::ReparentWindow}\label{wxframelayoutreparentwindow}

\func{void}{ReparentWindow}{\param{wxWindow* }{pChild}, \param{wxWindow* }{pNewParent}}

Reparents pChild to have parent pNewParent.


\membersection{wxFrameLayout::RepositionFloatedBar}\label{wxframelayoutrepositionfloatedbar}

\func{void}{RepositionFloatedBar}{\param{cbBarInfo* }{pBar}}

Applies the calculated layout to a floating bar.


\membersection{wxFrameLayout::RouteMouseEvent}\label{wxframelayoutroutemouseevent}

\func{void}{RouteMouseEvent}{\param{wxMouseEvent\& }{event}, \param{int }{pluginEvtType}}

Routes the mouse event to the appropriate pane.


\membersection{wxFrameLayout::SetBarState}\label{wxframelayoutsetbarstate}

\func{void}{SetBarState}{\param{cbBarInfo* }{pBar}, \param{int }{newStatem}, \param{bool }{updateNow}}

Changes the bar's docking state (see possible control bar states).


\membersection{wxFrameLayout::SetFrameClient}\label{wxframelayoutsetframeclient}

\func{void}{SetFrameClient}{\param{wxWindow* }{pFrameClient}}

Passes the client window (e.g. MDI client window) to be controlled by
frame layout, the size and position of which should be adjusted to be
surrounded by controlbar panes, whenever the frame is resized or the dimensions
of control panes change.


\membersection{wxFrameLayout::SetMargins}\label{wxframelayoutsetmargins}

\func{void}{SetMargins}{\param{int }{top}, \param{int }{bottom}, \param{int }{left}, \param{int }{right}, \param{int }{paneMask = wxALL\_PANES}}

Sets the margins for the given panes.
The margins should go into cbCommonPaneProperties in the future.
Note: this method should be called before any custom plugins are attached.


\membersection{wxFrameLayout::SetPaneBackground}\label{wxframelayoutsetpanebackground}

\func{void}{SetPaneBackground}{\param{const wxColour\& }{colour}}

Sets the pane background colour.


\membersection{wxFrameLayout::SetPaneProperties}\label{wxframelayoutsetpaneproperties}

\func{void}{SetPaneProperties}{\param{const cbCommonPaneProperties\& }{props}, \param{int }{paneMask = wxALL\_PANES}}

Sets the pane properties for the given alignment.
Note: changing properties of panes does not result immediate on-screen update.


\membersection{wxFrameLayout::SetTopPlugin}\label{wxframelayoutsettopplugin}

\func{void}{SetTopPlugin}{\param{cbPluginBase* }{pPlugin}}

Hooking custom plugins to frame layout.
Note: when hooking one plugin on top of the other,
use SetNextHandler or similar methods
of wxEvtHandler class to compose the chain of plugins,
than pass the left-most handler in this chain to
the above methods (assuming that events are delegated
from left-most towards right-most handler).
This secenario is very inconvenient and "low-level",
so use the Add/Push/PopPlugin methods instead.


\membersection{wxFrameLayout::SetUpdatesManager}\label{wxframelayoutsetupdatesmanager}

\func{void}{SetUpdatesManager}{\param{cbUpdatesManagerBase* }{pUMgr}}

Destroys the previous manager if any, and sets the new one.


\membersection{wxFrameLayout::ShowFloatedWindows}\label{wxframelayoutshowfloatedwindows}

\func{void}{ShowFloatedWindows}{\param{bool }{show}}

Shows all floated windows.


\membersection{wxFrameLayout::UnhookFromFrame}\label{wxframelayoutunhookfromframe}

\func{void}{UnhookFromFrame}{\void}

Unhooks the layout from the frame.