wxAuiNotebook(3)

okay bestie, welcome to wxAuiNotebook(3) — the Erlang Module Definition — and yes, this is part 1. 💖 We're talking the wxAUI notebook control, and it's lowkey iconic.

🌸 NAME 🌸

• wxAuiNotebook — this is part of the wxAUI class framework, and it's literally a notebook control that manages multiple windows with associated tabs. no cap. 🫶

✨ DESCRIPTION ✨

See also overview_aui.

wxAuiNotebook is a notebook control that implements many features common in applications with dockable panes. Specifically, it implements functionality that lets the user rearrange tab order via drag-and-drop, split the tab window into many different splitter configurations, and toggle through different themes to customize the control's look and feel. periodt. ✨

The default theme is wxAuiDefaultTabArt (not implemented in wx), and it's giving modern, glossy look and feel. You can change the theme by calling setArtProvider/2. 💅

🎀 Styles 🎀

bestie, this class supports the following styles — collect them all:

• wxAUI_NB_DEFAULT_STYLE — it's defined as wxAUI_NB_TOP | wxAUI_NB_TAB_SPLIT | wxAUI_NB_TAB_MOVE | wxAUI_NB_SCROLL_BUTTONS | wxAUI_NB_CLOSE_ON_ACTIVE_TAB | wxAUI_NB_MIDDLE_CLICK_CLOSE.
• wxAUI_NB_TAB_SPLIT — allows the tab control to be split by dragging a tab.
• wxAUI_NB_TAB_MOVE — allows a tab to be moved horizontally by dragging.
• wxAUI_NB_TAB_EXTERNAL_MOVE — allows a tab to be moved to another tab control.
• wxAUI_NB_TAB_FIXED_WIDTH — with this style, all tabs have the same width.
• wxAUI_NB_SCROLL_BUTTONS — with this style, left and right scroll buttons are displayed.
• wxAUI_NB_WINDOWLIST_BUTTON — with this style, a drop-down list of windows is available.
• wxAUI_NB_CLOSE_BUTTON — with this style, a close button is available on the tab bar.
• wxAUI_NB_CLOSE_ON_ACTIVE_TAB — with this style, the close button is visible on the active tab.
• wxAUI_NB_CLOSE_ON_ALL_TABS — with this style, the close button is visible on all tabs.
• wxAUI_NB_MIDDLE_CLICK_CLOSE — with this style, middle click on a tab closes the tab.
• wxAUI_NB_TOP — with this style, tabs are drawn along the top of the notebook.
• wxAUI_NB_BOTTOM — with this style, tabs are drawn along the bottom of the notebook.

This class is derived, and can use functions, from:

• wxControl
• wxWindow
• wxEvtHandler

wxWidgets docs: wxAuiNotebook

💖 Events 💖

event types emitted from this class are basically the group chat notifications:

• command_auinotebook_page_close
• command_auinotebook_page_closed
• command_auinotebook_page_changed
• command_auinotebook_page_changing
• command_auinotebook_button
• command_auinotebook_begin_drag
• command_auinotebook_end_drag
• command_auinotebook_drag_motion
• command_auinotebook_allow_dnd
• command_auinotebook_drag_done
• command_auinotebook_tab_middle_down
• command_auinotebook_tab_middle_up
• command_auinotebook_tab_right_down
• command_auinotebook_tab_right_up
• command_auinotebook_bg_dclick

🦋 DATA TYPES 🦋

wxAuiNotebook() :: wx:wx_object().

✨ FUNCTIONS ✨

🌸 addPage (the one with options) 🌸

       addPage(This, Page, Caption, [Option]) -> boolean()
                        when
                            This :: wxAuiNotebook(),
                            Page :: wxWindow:wxWindow(),
                            Caption :: unicode:chardata(),
                            Option ::
                                {select, boolean()} |
                                {bitmap, wxBitmap:wxBitmap()}.

okay so bestie, this one adds a page 🎀. and if you set the select parameter to true, calling this will literally generate a page change event. iykyk.

🦋 addPage (the full five-argument vibe) 🦋

       addPage(This, Page, Text, Select, ImageId) -> boolean()
                        when
                            This :: wxAuiNotebook(),
                            Page :: wxWindow:wxWindow(),
                            Text :: unicode:chardata(),
                            Select :: boolean(),
                            ImageId :: integer().

okay so this one adds a new page 💜. major key: the page must have the book control itself as the parent, and it must not have been added to this control previously. no cap. also, calling this function may generate the page changing events 👀.

return: true if it slays, false otherwise. periodt.

remark: do not delete the page — it will be deleted by the book control. so like, hands off bestie 🙈.

see: insertPage/6

since: 2.9.3 ✨

🌈 create (the one with two clauses) 🌈

       create(This, Parent, Winid) -> boolean()
                       when
                           This :: wxAuiNotebook(),
                           Parent :: wxWindow:wxWindow(),
                           Winid :: integer();
                   (This, Parent, [Option]) -> boolean()
                       when
                           This :: wxAuiNotebook(),
                           Parent :: wxWindow:wxWindow(),
                           Option ::
                               {id, integer()} |
                               {pos, {X :: integer(), Y :: integer()}} |
                               {size, {W :: integer(), H :: integer()}} |
                               {style, integer()}.

creates the notebook window 💅. that's it. that's the tweet.

🎀 create (the four-argument glow-up) 🎀

       create(This, Parent, Winid, [Option]) -> boolean()
                       when
                           This :: wxAuiNotebook(),
                           Parent :: wxWindow:wxWindow(),
                           Winid :: integer(),
                           Option ::
                               {pos, {X :: integer(), Y :: integer()}} |
                               {size, {W :: integer(), H :: integer()}} |
                               {style, integer()}.

constructs the book control with the given parameters ✨. iconic.

💀 deletePage 💀

       deletePage(This, Page) -> boolean()
                           when This :: wxAuiNotebook(), Page :: integer().

deletes a page at the given index 🔥. and heads up: calling this method will generate a page change event. so be ready.

🫶 destroy 🫶

       destroy(This :: wxAuiNotebook()) -> ok.

destroys the object 💥. bye bestie.

🌟 getArtProvider 🌟

       getArtProvider(This) -> wxAuiTabArt:wxAuiTabArt()
                               when This :: wxAuiNotebook().

returns the associated art provider 🎨. giving main character energy.

🍓 getPage 🍓

       getPage(This, Page_idx) -> wxWindow:wxWindow()
                        when This :: wxAuiNotebook(), Page_idx :: integer().

returns the page specified by the given index 🔍. got it.

✨ getPageBitmap ✨

       getPageBitmap(This, Page) -> wxBitmap:wxBitmap()
                              when This :: wxAuiNotebook(), Page :: integer().

returns the tab bitmap for the page 🖼️. cute.

👑 getPageCount 👑

       getPageCount(This) -> integer() when This :: wxAuiNotebook().

returns the number of pages in the notebook 🔢. periodt.

🌸 getPageIndex 🌸

       getPageIndex(This, Page_wnd) -> integer()
                             when
                                 This :: wxAuiNotebook(),
                                 Page_wnd :: wxWindow:wxWindow().

returns the page index for the specified window 🪟. and if the window is not found in the notebook, wxNOT_FOUND is returned. so watch out for that 💀.

💜 getPageText 💜

       getPageText(This, Page) -> unicode:charlist()
                            when This :: wxAuiNotebook(), Page :: integer().

returns the tab label for the page 🏷️. slay.

🔥 getSelection 🔥

       getSelection(This) -> integer() when This :: wxAuiNotebook().

returns the currently selected page 🎯. hot.

🦋 insertPage (the option-list version) 🦋

       insertPage(This, Page_idx, Page, Caption, [Option]) -> boolean()
                           when
                               This :: wxAuiNotebook(),
                               Page_idx :: integer(),
                               Page :: wxWindow:wxWindow(),
                               Caption :: unicode:chardata(),
                               Option ::
                                   {select, boolean()} |
                                   {bitmap, wxBitmap:wxBitmap()}.

insertPage/6 is similar to AddPage, but it allows the ability to specify the insert location 📍. and if the select parameter is true, calling this will generate a page change event. no cap.

🎀 insertPage (the full six-argument version) 🎀

       insertPage(This, Index, Page, Text, Select, ImageId) -> boolean()
                           when
                               This :: wxAuiNotebook(),
                               Index :: integer(),
                               Page :: wxWindow:wxWindow(),
                               Text :: unicode:chardata(),
                               Select :: boolean(),
                               ImageId :: integer().

inserts a new page at the specified position 📌.

return: true if it works, false otherwise.

remark: do not delete the page — it will be deleted by the book control. so like, don't even think about it 💀.

see: addPage/5

since: 2.9.3 ✨

🌈 new (no args) 🌈

       new() -> wxAuiNotebook().

default ctor 😌. simple. clean.

🦋 new (with Parent and options) 🦋

       new(Parent, [Option]) -> wxAuiNotebook()
                    when
                        Parent :: wxWindow:wxWindow(),
                        Option ::
                            {id, integer()} |
                            {pos, {X :: integer(), Y :: integer()}} |
                            {size, {W :: integer(), H :: integer()}} |
                            {style, integer()}.

constructor 🛠️. creates a wxAuiNotebok control. (yes, it's spelled like that in the original, we don't make the rules 💅).

💖 removePage 💖

       removePage(This, Page) -> boolean()
                           when This :: wxAuiNotebook(), Page :: integer().

removes a page, without deleting the window pointer 🚫🗑️. so like, it's still there, just not in the notebook. iykyk.

✨ setArtProvider ✨

       setArtProvider(This, Art) -> ok
                               when
                                   This :: wxAuiNotebook(),
                                   Art :: wxAuiTabArt:wxAuiTabArt().

sets the art provider to be used by the notebook 🎨. giving it a whole new look.

🌸 setFont 🌸

       setFont(This, Font) -> boolean()
                        when This :: wxAuiNotebook(), Font :: wxFont:wxFont().

sets the font for drawing the tab labels 🖋️, using a bold version of the font for selected tab labels. so selected tabs get that extra oomph 💪.

🍓 setPageBitmap 🍓

       setPageBitmap(This, Page, Bitmap) -> boolean()
                              when
                                  This :: wxAuiNotebook(),
                                  Page :: integer(),
                                  Bitmap :: wxBitmap:wxBitmap().

sets the bitmap for the page 🖼️. and heads up: to remove a bitmap from the tab caption, pass wxNullBitmap. boom.

💜 setPageText 💜

       setPageText(This, Page, Text) -> boolean()
                            when
                                This :: wxAuiNotebook(),
                                Page :: integer(),
                                Text :: unicode:chardata().

sets the tab label for the page 🏷️. slay.

🔥 setSelection 🔥

       setSelection(This, New_page) -> integer()
                             when
                                 This :: wxAuiNotebook(), New_page ::
       integer().

sets the page selection 🎯. and calling this method will generate a page change event. you've been warned.

👑 setTabCtrlHeight 👑

       setTabCtrlHeight(This, Height) -> ok
                                 when
                                     This :: wxAuiNotebook(),
                                     Height :: integer().

sets the tab height 📏. by default, the tab control height is calculated by measuring the text height and bitmap sizes on the tab captions. calling this method will override that calculation and set the tab control to the specified Height parameter. and a call to this method will override any call to setUniformBitmapSize/2. big moves.

specifying -1 as the height will return the control to its default auto-sizing behaviour. so like, undo it.

🌟 setUniformBitmapSize 🌟

       setUniformBitmapSize(This, Size) -> ok
                                     when
                                         This :: wxAuiNotebook(),
                                         Size ::
                                             {W :: integer(), H :: integer()}.

ensure that all tabs have the same height, even if some of them don't have bitmaps 📐. equality.

passing ?wxDefaultSize as Size undoes the effect of a previous call to this function and instructs the control to use dynamic tab height. so it's like a reset button 🔄.

---

and that's a wrap, bestie 💅. this masterpiece was brought to you by Ericsson AB, running on wx 2.6, and it's the wxAuiNotebook(3) man page. no date in sight, just vibes. periodt. 💖✨