438 lines
14 KiB
Objective-C
438 lines
14 KiB
Objective-C
/////////////////////////////////////////////////////////////////////////////
|
|
// Name: aui/serializer.h
|
|
// Purpose: Documentation of wxAuiSerializer and wxAuiDeserializer.
|
|
// Author: Vadim Zeitlin
|
|
// Created: 2024-02-20
|
|
// Copyright: (c) 2024 Vadim Zeitlin <vadim@wxwidgets.org>
|
|
// Licence: wxWindows licence
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
/**
|
|
Description of a docked element layout.
|
|
|
|
The fields in this struct are shared by wxAuiPaneLayoutInfo and
|
|
wxAuiTabLayoutInfo and contain information about the layout of a docked
|
|
pane or tab layout.
|
|
|
|
Note that when saving the objects of this type, fields that have the value
|
|
of 0 can be omitted, as this is their default value in any case (except for
|
|
`dock_direction` which is never 0), to make the serialized representation
|
|
more compact.
|
|
|
|
@since 3.3.0
|
|
*/
|
|
struct wxAuiDockLayoutInfo
|
|
{
|
|
/// Direction of the dock containing the pane.
|
|
int dock_direction = wxAUI_DOCK_LEFT;
|
|
|
|
/// Layer of the dock containing the pane.
|
|
int dock_layer = 0;
|
|
|
|
/// Row of the dock containing the pane.
|
|
int dock_row = 0;
|
|
|
|
/// Position of the pane in the dock containing it.
|
|
int dock_pos = 0;
|
|
|
|
/// Relative proportion of the dock allocated to this pane.
|
|
int dock_proportion = 0;
|
|
|
|
/// Size of the containing dock.
|
|
int dock_size = 0;
|
|
};
|
|
|
|
/**
|
|
Contains information about the layout of a tab control in a wxAuiNotebook.
|
|
|
|
This includes where it is docked, via the fields inherited from
|
|
wxAuiDockLayoutInfo, and, optionally, the order of pages in it if it was
|
|
changed as well as pinned pages indices, if any.
|
|
|
|
@since 3.3.0
|
|
*/
|
|
struct wxAuiTabLayoutInfo : wxAuiDockLayoutInfo
|
|
{
|
|
/**
|
|
Indices of the pages in this tab control in their order on screen.
|
|
|
|
If this vector is empty, it means that the tab control contains all
|
|
notebook pages in natural order.
|
|
*/
|
|
std::vector<int> pages;
|
|
|
|
/**
|
|
Indices of the pinned pages in this tab control.
|
|
|
|
This vector can be empty if there are no pinned pages in this tab
|
|
control. Otherwise it should be a subset of the `pages` vector if it is
|
|
not empty.
|
|
*/
|
|
std::vector<int> pinned;
|
|
|
|
/**
|
|
Index of the currently selected page in this tab control.
|
|
|
|
Note that the value of this field is a page index in the notebook, not
|
|
the position of the active tab in this tab control, and should be one
|
|
of the elements of the `pages` vector if it is not empty.
|
|
*/
|
|
int active = 0;
|
|
};
|
|
|
|
/**
|
|
Description of user-modifiable pane layout information.
|
|
|
|
This struct is used with wxAuiSerializer and wxAuiDeserializer to store the
|
|
pane layout. Its fields, including the inherited ones from
|
|
wxAuiDockLayoutInfo, have the same meaning as the corresponding fields in
|
|
wxAuiPaneInfo (with the exception of `is_maximized` and `is_hidden`, which
|
|
rather correspond to the individual bits of its state field), but it
|
|
doesn't contain the fields that it wouldn't make sense to serialize.
|
|
|
|
@since 3.3.0
|
|
*/
|
|
struct wxAuiPaneLayoutInfo : wxAuiDockLayoutInfo
|
|
{
|
|
/**
|
|
Ctor sets the name, which is always required.
|
|
*/
|
|
explicit wxAuiPaneLayoutInfo(wxString name);
|
|
|
|
/// Unique name of the pane.
|
|
wxString name;
|
|
|
|
/// Position of the pane when floating, may be invalid.
|
|
wxPoint floating_pos = wxDefaultPosition;
|
|
|
|
/// Size of the pane when floating, may be invalid.
|
|
wxSize floating_size = wxDefaultSize;
|
|
|
|
|
|
/// True if the pane is currently maximized.
|
|
bool is_maximized = false;
|
|
|
|
/// True if the pane is currently hidden.
|
|
bool is_hidden = false;
|
|
};
|
|
|
|
/**
|
|
@class wxAuiBookSerializer
|
|
|
|
wxAuiBookSerializer is used for serializing wxAuiNotebook layout.
|
|
|
|
This includes the tab controls layout and the order of pages in them.
|
|
|
|
It can be used standalone with wxAuiNotebook::SaveLayout() or as base class
|
|
of wxAuiSerializer for saving and restoring the entire layout.
|
|
|
|
@library{wxaui}
|
|
@category{aui}
|
|
|
|
@since 3.3.0
|
|
*/
|
|
class wxAuiBookSerializer
|
|
{
|
|
public:
|
|
/// Trivial default ctor.
|
|
wxAuiBookSerializer() = default;
|
|
|
|
/// Trivial but virtual destructor.
|
|
virtual ~wxAuiBookSerializer() = default;
|
|
|
|
/**
|
|
Called before starting to save information about the tabs in the
|
|
notebook in the AUI pane with the given name.
|
|
|
|
This function needs to be overridden to keep record of the notebook for
|
|
which SaveNotebookTabControl() will be called next.
|
|
|
|
If this class is used as a base class of wxAuiSerializer, saving
|
|
notebook layout may be unnecessary, e.g. because the program doesn't
|
|
use wxAuiNotebook at all, and the implementation can be trivial and
|
|
just do nothing because it is not going to be called at all if there
|
|
are no notebooks in the full layout.
|
|
|
|
When using wxAuiNotebook::SaveLayout() directly, this function is
|
|
always called and is the first function of this class to be called.
|
|
*/
|
|
virtual void BeforeSaveNotebook(const wxString& name) = 0;
|
|
|
|
/**
|
|
Called to save information about a single tab control in the given
|
|
notebook.
|
|
|
|
This function will be called for all tab controls in the notebook after
|
|
BeforeSaveNotebook().
|
|
|
|
As with that function, it has to be implemented, but can simply do
|
|
nothing if saving notebook layout is not necessary.
|
|
*/
|
|
virtual void SaveNotebookTabControl(const wxAuiTabLayoutInfo& tab) = 0;
|
|
|
|
/**
|
|
Called after saving information about all the pages of the notebook in
|
|
the AUI pane with the given name.
|
|
|
|
Does nothing by default.
|
|
*/
|
|
virtual void AfterSaveNotebook();
|
|
|
|
};
|
|
|
|
/**
|
|
@class wxAuiSerializer
|
|
|
|
wxAuiSerializer is used by wxAuiManager::SaveLayout() to store layout
|
|
information.
|
|
|
|
This is an abstract base class, you need to inherit from it and override its
|
|
pure virtual functions, including those inherited from its base
|
|
wxAuiBookSerializer class, in your derived class.
|
|
|
|
In particular, SavePane() must be overridden and will be called by
|
|
wxAuiManager for each pane and dock present in the layout. Most of the
|
|
other functions don't need to be overridden, but it is often convenient to
|
|
perform some actions before or after starting to save the objects of the
|
|
given type or at the beginning or end of the whole saving process, so this
|
|
class provides hooks for doing it.
|
|
|
|
If any of the functions of the derived class throw an exception, it is
|
|
propagated out of wxAuiManager::SaveLayout() and it's callers responsibility
|
|
to handle it.
|
|
|
|
@library{wxaui}
|
|
@category{aui}
|
|
|
|
@since 3.3.0
|
|
*/
|
|
class wxAuiSerializer : public wxAuiBookSerializer
|
|
{
|
|
public:
|
|
/// Trivial default ctor.
|
|
wxAuiSerializer() = default;
|
|
|
|
/**
|
|
Called before doing anything else.
|
|
|
|
Does nothing by default.
|
|
*/
|
|
virtual void BeforeSave();
|
|
|
|
/**
|
|
Called before starting to save information about the panes.
|
|
|
|
Does nothing by default.
|
|
*/
|
|
virtual void BeforeSavePanes();
|
|
|
|
/**
|
|
Save information about the given pane.
|
|
|
|
This function will be called for all panes and must be implemented to
|
|
save their data in a format from which it can be restored later using a
|
|
matching wxAuiDeserializer implementation.
|
|
|
|
Note that all sizes and positions in @a pane are using DIPs, i.e.
|
|
resolution-independent pixels, when it is passed to this function, so
|
|
it does _not_ need to perform any scaling itself to ensure that the
|
|
stored values are restored correctly if the resolution changes.
|
|
*/
|
|
virtual void SavePane(const wxAuiPaneLayoutInfo& pane) = 0;
|
|
|
|
/**
|
|
Called after the last call to SavePane().
|
|
|
|
Does nothing by default.
|
|
*/
|
|
virtual void AfterSavePanes();
|
|
|
|
/**
|
|
Called before starting to save information about the notebooks.
|
|
|
|
Does nothing by default.
|
|
|
|
Note that this function is called after AfterSavePanes() but may not be
|
|
called at all if there are no panes containing wxAuiNotebook.
|
|
|
|
wxAuiBookSerializer member functions will be called after this function
|
|
if it is called at all.
|
|
*/
|
|
virtual void BeforeSaveNotebooks();
|
|
|
|
/**
|
|
Called after the last call to SaveNotebook().
|
|
|
|
Does nothing by default.
|
|
|
|
This function is called after all wxAuiBookSerializer member functions
|
|
*/
|
|
virtual void AfterSaveNotebooks();
|
|
|
|
/**
|
|
Called after saving everything.
|
|
|
|
Does nothing by default.
|
|
*/
|
|
virtual void AfterSave();
|
|
};
|
|
|
|
/**
|
|
wxAuiBookDeserializer is used for deserializing wxAuiNotebook layout.
|
|
|
|
Similarly to wxAuiBookSerializer, it can be used standalone with
|
|
wxAuiNotebook::LoadLayout() or as base class of wxAuiDeserializer.
|
|
|
|
@library{wxaui}
|
|
@category{aui}
|
|
|
|
@since 3.3.0
|
|
*/
|
|
class wxAuiBookDeserializer
|
|
{
|
|
public:
|
|
/// Trivial default ctor.
|
|
wxAuiBookDeserializer() = default;
|
|
|
|
/// Trivial but virtual destructor.
|
|
virtual ~wxAuiBookDeserializer() = default;
|
|
|
|
/**
|
|
Load information about the notebook tabs previously saved by
|
|
wxAuiBookSerializer::SaveNotebookTabControl().
|
|
|
|
When using this class as a base class of wxAuiDeserializer, this
|
|
function is called by wxAuiManager::LoadLayout() after loading the pane
|
|
with the name @a name if it is a wxAuiNotebook. Otherwise, i.e. when
|
|
using wxAuiNotebook::LoadLayout() directly, this function is called
|
|
with the same @a name as was passed to that function.
|
|
|
|
If restoring the notebook layout is not necessary, this function can
|
|
just return an empty vector which is interpreted as meaning that the
|
|
default notebook layout should be used.
|
|
*/
|
|
virtual std::vector<wxAuiTabLayoutInfo>
|
|
LoadNotebookTabs(const wxString& name) = 0;
|
|
|
|
/**
|
|
Determine what should be done with the pages not attached to any tab
|
|
control after restoring the pages order.
|
|
|
|
It is possible that the data returned by LoadNotebookTabs() doesn't
|
|
contain the layout information for all the currently existing pages,
|
|
e.g. because data saved by an earlier program version is being loaded
|
|
into a newer version in which new pages were added. In this case, this
|
|
function is called for each @a page that wasn't assigned to any tab
|
|
after restoring the pages order and can be overridden to determine what
|
|
should be done with it.
|
|
|
|
The default implementation of this function just returns @true without
|
|
modifying the output arguments, which results in the page being
|
|
appended to the main tab control. The overridden version may return
|
|
@true but modify @a tabCtrl and @a tabIndex arguments to change where
|
|
the page should be inserted, e.g. by setting @a tabIndex to 0 to insert
|
|
the new pages at the beginning instead of appending them.
|
|
|
|
Finally, the overridden function may return @false to indicate that the
|
|
page should be removed from the notebook.
|
|
|
|
@note The @a book parameter can be used to retrieve the total number of
|
|
pages or to call functions such as wxAuiNotebook::GetMainTabCtrl()
|
|
or wxAuiNotebook::GetAllTabCtrls() on it, but this function must
|
|
not attempt to modify it by adding or removing pages to/from it.
|
|
*/
|
|
virtual bool
|
|
HandleOrphanedPage(wxAuiNotebook& book,
|
|
int page,
|
|
wxAuiTabCtrl** tabCtrl,
|
|
int* tabIndex);
|
|
};
|
|
|
|
/**
|
|
@class wxAuiDeserializer
|
|
|
|
wxAuiDeserializer is used by wxAuiManager::LoadLayout() to restore layout
|
|
information saved by wxAuiManager::SaveLayout().
|
|
|
|
As wxAuiSerializer, this is an abstract base class, you need to inherit from
|
|
it and override its pure virtual functions in your derived class.
|
|
|
|
Derived class function also may throw and, if any of them other than
|
|
AfterLoad() does, the existing layout is not changed, i.e.
|
|
wxAuiManager::LoadLayout() is exception-safe.
|
|
|
|
@library{wxaui}
|
|
@category{aui}
|
|
|
|
@since 3.3.0
|
|
*/
|
|
class wxAuiDeserializer : public wxAuiBookDeserializer
|
|
{
|
|
public:
|
|
/**
|
|
Constructor taking the manager for which we're restoring the layout.
|
|
|
|
The manager remains valid for the lifetime of this object.
|
|
*/
|
|
explicit wxAuiDeserializer(wxAuiManager& manager);
|
|
|
|
/// Trivial but virtual destructor.
|
|
virtual ~wxAuiDeserializer() = default;
|
|
|
|
|
|
/**
|
|
Called before doing anything else.
|
|
|
|
Does nothing by default.
|
|
*/
|
|
virtual void BeforeLoad();
|
|
|
|
/**
|
|
Load information about all the panes previously saved by
|
|
wxAuiSerializer::SavePane().
|
|
|
|
Unlike the serializer function, this one is called only once and should
|
|
return all the panes in the layout.
|
|
|
|
Just as the serializer function, this one doesn't need to perform any
|
|
scaling itself as this will be done, if necessary, by wxAuiManager
|
|
itself.
|
|
|
|
If some pane in the returned vector doesn't already exist, i.e. there
|
|
is no pane with the matching name, CreatePaneWindow() is called to
|
|
allow creating it on the fly.
|
|
*/
|
|
virtual std::vector<wxAuiPaneLayoutInfo> LoadPanes() = 0;
|
|
|
|
/**
|
|
Create the window to be managed by the given pane if necessary.
|
|
|
|
This function is called if any of the panes returned by LoadPanes()
|
|
doesn't exist in the existing layout and allows to create windows on
|
|
the fly.
|
|
|
|
If this function returns @NULL, as it does by default, the pane is not
|
|
added to the manager.
|
|
|
|
If the function does create a new window, it should typically modify @a
|
|
pane parameter to fill in the fields such as `caption` or `icon` that
|
|
wouldn't normally be serialized and so wouldn't be restored by
|
|
LoadPanes().
|
|
*/
|
|
virtual wxWindow* CreatePaneWindow(wxAuiPaneInfo& pane);
|
|
|
|
/**
|
|
Called after restoring everything.
|
|
|
|
Default implementation calls wxAuiManager::Update(). Override this
|
|
function and do _not_ call the base class version if you want to
|
|
prevent this from happening, e.g. if you need to make further changes
|
|
to the restored layout before updating it.
|
|
*/
|
|
virtual void AfterLoad();
|
|
|
|
protected:
|
|
/// The manager for which we're restoring the layout.
|
|
wxAuiManager& m_manager;
|
|
};
|