Wx::Notebook

From WxPerl wiki

This class represents a notebook control, which manages multiple windows with associated tabs.

To use the class, create a Wx::Notebook object, then call AddPage or InsertPage, passing a window to be used as the page. Generally, you will use a Wx::Panel as the page.

A demo program is available: Wx::Notebook Demo.

Contents 1 Inheritance 2 Styles 3 Events 4 Constructor 4.1 new 5 Methods 5.1 AddPage 5.2 AdvanceSelection 5.3 AssignImageList 5.4 ChangeSelection 5.5 Create 5.6 DeleteAllPages 5.7 DeletePage 5.8 GetCurrentPage 5.9 GetImageList 5.10 GetPage 5.11 GetPageCount 5.12 GetPageImage 5.13 GetPageText 5.14 GetRowCount 5.15 GetSelection 5.16 GetThemeBackgroundColour 5.17 HitTest 5.18 InsertPage 5.19 RemovePage 5.20 SetImageList 5.21 SetPadding 5.22 SetPageSize 5.23 SetPageImage 5.24 SetPageText 5.25 SetSelection 6 Page Backgrounds 7 Unimplemented Methods 7.1 OnSelChange

Inheritance

Wx::Notebook derives from Wx::Control, Wx::Window, Wx::EvtHandler, and Wx::Object.

Styles

wxNB_TOP	Place tabs on the top side.
wxNB_LEFT	Place tabs on the left side.
wxNB_RIGHT	Place tabs on the right side.
wxNB_BOTTOM	Place tabs under instead of above the notebook pages.
wxNB_FIXEDWIDTH	(Windows only) All tabs will have same width.
wxNB_MULTILINE	(Windows only) There can be several rows of tabs.
wxNB_NOPAGETHEME	(Windows only) Display a solid colour on notebook pages, and not a gradient, which can reduce performance.
wxNB_FLAT	(Windows CE only) Show tabs in a flat style.

The styles wxNB_LEFT, wxNB_RIGHT and wxNB_BOTTOM are not supported under Microsoft Windows XP when using visual themes.

Events

Event	Parameters	Description
EVT_NOTEBOOK_PAGE_CHANGED	$win, $nb_ctrl, \&func	The page selection was changed.
EVT_NOTEBOOK_PAGE_CHANGING	$win, $nb_ctrl, \&func	The page selection is about to be changed. This event can be vetoed; see Wx::NotifyEvent::Veto.

Constructor

new

$nb = Wx::Notebook->new($parent, $id, $pos, $size, $style, $name);

Param	Description
$parent	Parent window object, must not be undef.
$id	An integer specifying the window identifier. Usually you will specify -1 to let the system assign a window ID automatically.
$pos	The control position, a reference to an array containing an x and a y coordinate. The special value [-1, -1] tells the system to choose the window's starting position. Optional.
$size	The size of the control. Usually you will specify [-1, -1] to tell the system to use a default size. Optional.
$style	The style(s) to apply to this control; see above. Optional.
$name	The name of the control. This parameter is used to associate a name with the control, which allows certain windowing systems to search for the window by name, and allows X resources values to be applied to the window by name.

Methods

AddPage

$bool = $nb->AddPage($page, $text, $select, $image_id);

Adds a new page.

The call to this function may generate the page changing events.

Param	Description
$page	The page to be added. Must be a Wx::Window object (often a Wx::Panel.
$text	Specifies the text (tab label) for the new page.
$select	Boolean. If true, the new page will be selected after it is added. Optional; defaults to false.
$image_id	Integer. Optional. Specifies the image index to use for the new page.

AdvanceSelection

$nb->AdvanceSelection($forward);

Cycles through the tabs. Calling this function will generate the page-changing events.

Param	Description
$forward	Boolean. If true, selects the next tab; if false, the previous. Optional; defaults to true.

AssignImageList

$nb->AssignImageList($image_list);

Sets the image list for the control, and takes ownership of the list. $image_list is a Wx::ImageList object.

ChangeSelection

$old_page_num = $nb->ChangeSelection($page_num);

Changes the selection for the given page, returning the previous selection. Page numbers are 0-based.

The call to this function does not generate the page-changing events. This is the only difference with SetSelection.

Create

$bool = $nb->Create($parent, $id, $pos, $size, $style, $name);

Creates a notebook control. See new for a description of the parameters.

DeleteAllPages

$bool = $nb->DeleteAllPages();

Deletes all pages.

DeletePage

$bool = $nb->DeletePage($page);

Deletes the specified page, and its associated window.

The call to this function generates the page changing events.

GetCurrentPage

$page = $nb->GetCurrentPage();

Returns the currently selected notebook page, or undef if none is selected.

GetImageList

$list $nb->GetImageList();

Returns the associated image list.

See also Wx::ImageList, SetImageList

GetPage

$win = $nb->GetPage($page_num);

Returns the window at the given (0-based) page position.

GetPageCount

$num = $nb->GetPageCount();

Returns the number of pages in the notebook control.

GetPageImage

$index = $nb->GetPageImage($page_num);

Returns the image index for the given page.

GetPageText

$text = $nb->GetPageText($page_num);

Returns the tab label string for the given page.

GetRowCount

$num = $nb->GetRowCount();

Returns the number of rows in the notebook control.

GetSelection

$page_num = $nb->GetSelection();

Returns the (0-based) number of the currently selected page, or -1 if none was selected.

Note that this method may return either the previously or newly selected page when called from the EVT_NOTEBOOK_PAGE_CHANGED handler depending on the platform. Instead, use GetSelection in that case.

GetThemeBackgroundColour

$color = $nb->GetThemeBackgroundColour();

If running under Windows and themes are enabled for the application, this function returns a suitable colour for painting the background of a notebook page, and can be passed to SetBackgroundColour. Otherwise, an uninitialised colour will be returned.

HitTest

($page_num, $flags) = $nb->HitTest($pos);

Given a point ($pos, a Wx::Point object or two-element arrayref [$x, $y]) relative to the origin of the Notebook control, indicates what tab is under that point, if any.

On return, $page_num will be the page number of the tab under the specified point, or wxNOT_FOUND (-1) if no tab is at that point.

$flags will be set to a bitwise-OR of one or more of the following values:

Flag	Description
wxBK_HITTEST_NOWHERE	There was no tab under this point.
wxBK_HITTEST_ONICON	The point was over an icon (this is currently only valid for MS Windows).
wxBK_HITTEST_ONLABEL	The point was over a label (this is currently only valid for MS Windows).
wxBK_HITTEST_ONITEM	The point was over a tab, but not on the label or icon itself.
wxBK_HITTEST_ONPAGE	The point was over a currently-selected page, not over any tab. This flag can only be present if the returned $page_num is wxNOT_FOUND.

These constants are all exported by Wx, with the :bookctrl or :everything tags.

The flags should be tested by using bitwise-AND (&) against the specified constants:

($page_num, $flags) = $nb->HitTest($pos);
if ($flags & wxBK_HITTEST_ONICON)
{
    ...

InsertPage

$bool = $nb->InsertPage($index, $page, $text, $select, $image_id);

Inserts a new page at the specified position.

Param	Description
$index	Specifies the position for the new page.
$page	The page to insert, a wxWindow object.
$text	Specifies the text for the new page's tab label.
$select	Specifies whether the page should be selected. Optional; defaults to false.
$image_id	Specifies the optional image index for the new page.

Returns true if successful, false otherwise.

Remarks

Do not delete the page, it will be deleted by the notebook.

See also: AddPage.

RemovePage

$bool = $nb->RemovePage($page_num);

Deletes the specified page. Does not delete the associated window.

SetImageList

$nb->SetImageList($image_list);

Sets the image list for the page control.

See also Wx::ImageList, AssignImageList.

SetPadding

$nb->SetPadding($padding);

Sets the amount of space around each page's icon and label, in pixels. $padding is a Wx::Size object, or an arrayref of [$horiz, $vert] values.

NB: The vertical padding cannot be changed in wxGTK.

SetPageSize

$nb->SetPageSize($size);

Sets the width and height of the pages. $size if a Wx::Size objecxt, or an arrayref of [$width, $height] values.

NB: This method is currently not implemented for wxGTK.

SetPageImage

$bool = $nb->SetPageImage($page_num, $image);

Sets the image index for the given page. $image is an index into the image list which was set with SetImageList.

SetPageText

$bool = $nb->SetPageText($page_num, $text);

Sets the text for the tab label of the given page.

SetSelection

$old_page = $nb->SetSelection($page_num);

Selects the given page, returning the number of the page that was previously selected.

The call to this function does generate the page changing events.

This function is deprecated and should not be used in new code. Please use the ChangeSelection function instead.

See also GetSelection.

Page Backgrounds

On Windows XP, the default theme paints a gradient on the notebook's pages. If you wish to suppress this theme, for aesthetic or performance reasons, there are three ways of doing it. You can use wxNB_NOPAGETHEME to disable themed drawing for a particular notebook, you can call wxSystemOptions::SetOption to disable it for the whole application, or you can disable it for individual pages by using SetBackgroundColour.

To disable themed pages globally:

   wxSystemOptions::SetOption("msw.notebook.themed-background", 0);

Set the value to 1 to enable it again.

To give a single page a solid background that more or less fits in with the overall theme, use:

   $color = $nb->GetThemeBackgroundColour();
   if ($color->IsOk)
   {
       $page->SetBackgroundColour($color);
   }

On platforms other than Windows, or if the application is not using Windows themes, GetThemeBackgroundColour will return an uninitialised colour object, and the above code will therefore work on all platforms.

Unimplemented Methods

The following methods does not seem to be implemented in WxPerl:

OnSelChange