// Name: editors.h
// Purpose: interface of wxPropertyGrid editors
// Author: wxWidgets team
-// RCS-ID: $Id:
-// Licence: wxWindows license
+// RCS-ID: $Id$
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
-// -----------------------------------------------------------------------
-/** @class wxPGEditor
+/**
+ @class wxPGEditor
Base class for custom wxPropertyGrid editors.
@remarks
- - Names of builtin property editors are: TextCtrl, Choice,
- ComboBox, CheckBox, TextCtrlAndButton, and ChoiceAndButton. Additional editors
- include SpinCtrl and DatePickerCtrl, but using them requires calling
- wxPropertyGrid::RegisterAdditionalEditors() prior use.
+ - Names of built-in property editors are: TextCtrl, Choice,
+ ComboBox, CheckBox, TextCtrlAndButton, and ChoiceAndButton. Additional
+ editors include SpinCtrl and DatePickerCtrl, but using them requires
+ calling wxPropertyGrid::RegisterAdditionalEditors() prior use.
- - Pointer to builtin editor is available as wxPGEditor_EditorName
+ - Pointer to built-in editor is available as wxPGEditor_EditorName
(eg. wxPGEditor_TextCtrl).
- - To add new editor you need to register it first using static function
+ - Before you start using new editor you just created, you need to register
+ it using static function
wxPropertyGrid::RegisterEditorClass(), with code like this:
@code
wxPGEditor* editorPointer = wxPropertyGrid::RegisterEditorClass(new MyEditorClass(), "MyEditor");
public:
/** Constructor. */
- wxPGEditor()
- : wxObject()
- {
- m_clientData = NULL;
- }
+ wxPGEditor();
/** Destructor. */
virtual ~wxPGEditor();
- /** Returns pointer to the name of the editor. For example, wxPG_EDITOR(TextCtrl)
- has name "TextCtrl". This method is autogenerated for custom editors.
+ /**
+ Returns pointer to the name of the editor. For example,
+ wxPGEditor_TextCtrl has name "TextCtrl". If you dont' need to access
+ your custom editor by string name, then you do not need to implement
+ this function.
*/
- virtual wxString GetName() const = 0;
+ virtual wxString GetName() const;
+
+ /**
+ Instantiates editor controls.
- /** Instantiates editor controls.
@param propgrid
- wxPropertyGrid to which the property belongs (use as parent for control).
+ wxPropertyGrid to which the property belongs (use as parent for control).
+
@param property
- Property for which this method is called.
+ Property for which this method is called.
+
@param pos
- Position, inside wxPropertyGrid, to create control(s) to.
+ Position, inside wxPropertyGrid, to create control(s) to.
+
@param size
- Initial size for control(s).
+ Initial size for control(s).
@remarks
- Primary control shall use id wxPG_SUBID1, and secondary (button) control
shall use wxPG_SUBID2.
- - Implementation shoud use connect all necessary events to the
- wxPropertyGrid::OnCustomEditorEvent. For Example:
- @code
- // Relays wxEVT_COMMAND_TEXT_UPDATED events of primary editor
- // control to the OnEvent.
- // NOTE: This event in particular is actually automatically conveyed, but
- // it is just used as an example.
- propgrid->Connect( wxPG_SUBID1, wxEVT_COMMAND_TEXT_UPDATED,
- wxCommandEventHandler(wxPropertyGrid::OnCustomEditorEvent) );
- @endcode
- OnCustomEditorEvent will then forward events, first to wxPGEditor::OnEvent and then to wxPGProperty::OnEvent.
-
+ - Unlike in previous version of wxPropertyGrid, it is no longer
+ necessary to call wxEvtHandler::Connect() for interesting editor
+ events. Instead, all events from control are now automatically
+ forwarded to wxPGEditor::OnEvent() and wxPGProperty::OnEvent().
*/
- virtual wxPGWindowList CreateControls( wxPropertyGrid* propgrid, wxPGProperty* property,
- const wxPoint& pos, const wxSize& size ) const = 0;
+ virtual wxPGWindowList CreateControls( wxPropertyGrid* propgrid,
+ wxPGProperty* property,
+ const wxPoint& pos,
+ const wxSize& size ) const = 0;
/** Loads value from property to the control. */
virtual void UpdateControl( wxPGProperty* property, wxWindow* ctrl ) const = 0;
- /** Draws value for given property.
+ /**
+ Draws value for given property.
*/
- virtual void DrawValue( wxDC& dc, const wxRect& rect, wxPGProperty* property, const wxString& text ) const;
-
- /** Handles events. Returns true if value in control was modified
- (see wxPGProperty::OnEvent for more information).
+ virtual void DrawValue( wxDC& dc, const wxRect& rect,
+ wxPGProperty* property, const wxString& text ) const;
+
+ /**
+ Handles events. Returns @true if value in control was modified
+ (see wxPGProperty::OnEvent() for more information).
+
+ @remarks wxPropertyGrid will automatically unfocus the editor when
+ wxEVT_COMMAND_TEXT_ENTER is received and when it results in
+ property value being modified. This happens regardless of
+ editor type (ie. behavior is same for any wxTextCtrl and
+ wxComboBox based editor).
*/
virtual bool OnEvent( wxPropertyGrid* propgrid, wxPGProperty* property,
wxWindow* wnd_primary, wxEvent& event ) const = 0;
- /** Returns value from control, via parameter 'variant'.
- Usually ends up calling property's StringToValue or IntToValue.
- Returns true if value was different.
+ /**
+ Returns value from control, via parameter 'variant'.
+ Usually ends up calling property's StringToValue() or IntToValue().
+ Returns @true if value was different.
*/
- virtual bool GetValueFromControl( wxVariant& variant, wxPGProperty* property, wxWindow* ctrl ) const;
+ virtual bool GetValueFromControl( wxVariant& variant, wxPGProperty* property,
+ wxWindow* ctrl ) const;
/** Sets value in control to unspecified. */
- virtual void SetValueToUnspecified( wxPGProperty* property, wxWindow* ctrl ) const = 0;
+ virtual void SetValueToUnspecified( wxPGProperty* property,
+ wxWindow* ctrl ) const = 0;
+
+ /**
+ Called by property grid to set new appearance for the control.
+ Default implementation sets foreground colour, background colour,
+ font, plus text for wxTextCtrl and wxComboCtrl.
+
+ The parameter @a appearance represents the new appearance to be applied.
+
+ The parameter @a oldAppearance is the previously applied appearance.
+ Used to detect which control attributes need to be changed (e.g. so we only
+ change background colour if really needed).
+
+ Finally, the parameter @a unspecified if @true tells this function that
+ the new appearance represents an unspecified property value.
+ */
+ virtual void SetControlAppearance( wxPropertyGrid* pg,
+ wxPGProperty* property,
+ wxWindow* ctrl,
+ const wxPGCell& appearance,
+ const wxPGCell& oldAppearance,
+ bool unspecified ) const;
/** Sets control's value specifically from string. */
- virtual void SetControlStringValue( wxPGProperty* property, wxWindow* ctrl, const wxString& txt ) const;
+ virtual void SetControlStringValue( wxPGProperty* property,
+ wxWindow* ctrl, const wxString& txt ) const;
/** Sets control's value specifically from int (applies to choice etc.). */
- virtual void SetControlIntValue( wxPGProperty* property, wxWindow* ctrl, int value ) const;
+ virtual void SetControlIntValue( wxPGProperty* property,
+ wxWindow* ctrl, int value ) const;
- /** Inserts item to existing control. Index -1 means appending.
+ /**
+ Inserts item to existing control. Index -1 means end of list.
Default implementation does nothing. Returns index of item added.
*/
virtual int InsertItem( wxWindow* ctrl, const wxString& label, int index ) const;
- /** Deletes item from existing control.
+ /**
+ Deletes item from existing control.
Default implementation does nothing.
*/
virtual void DeleteItem( wxWindow* ctrl, int index ) const;
- /** Extra processing when control gains focus. For example, wxTextCtrl
- based controls should select all text.
+ /**
+ Extra processing when control gains focus.
+ For example, wxTextCtrl based controls should select all text.
*/
virtual void OnFocus( wxPGProperty* property, wxWindow* wnd ) const;
- /** Returns true if control itself can contain the custom image. Default is
- to return false.
+ /**
+ Returns @true if control itself can contain the custom image.
+ Default implementation returns @false.
*/
virtual bool CanContainCustomImage() const;
-
- //
- // This member is public so scripting language bindings
- // wrapper code can access it freely.
- void* m_clientData;
};
-// -----------------------------------------------------------------------
-/** @class wxPGMultiButton
+
+/**
+ @class wxPGMultiButton
This class can be used to have multiple buttons in a property editor.
You will need to create a new property editor class, override CreateControls,
and have it return wxPGMultiButton instance in wxPGWindowList::SetSecondary().
- For instance, here we add three buttons to a textctrl editor:
- @code
+ For instance, here we add three buttons to a TextCtrl editor:
+ @code
#include <wx/propgrid/editors.h>
- class wxMultiButtonTextCtrlEditor : public wxPGTextCtrlEditor
+ class wxSampleMultiButtonEditor : public wxPGTextCtrlEditor
{
- WX_PG_DECLARE_EDITOR_CLASS(wxMultiButtonTextCtrlEditor)
+ wxDECLARE_DYNAMIC_CLASS(wxSampleMultiButtonEditor);
+
public:
- wxMultiButtonTextCtrlEditor() {}
- virtual ~wxMultiButtonTextCtrlEditor() {}
+ wxSampleMultiButtonEditor() {}
+ virtual ~wxSampleMultiButtonEditor() {}
+
+ virtual wxString GetName() const { return "SampleMultiButtonEditor"; }
- wxPG_DECLARE_CREATECONTROLS
+ virtual wxPGWindowList CreateControls( wxPropertyGrid* propGrid,
+ wxPGProperty* property,
+ const wxPoint& pos,
+ const wxSize& sz ) const;
virtual bool OnEvent( wxPropertyGrid* propGrid,
wxPGProperty* property,
wxWindow* ctrl,
wxEvent& event ) const;
-
};
- WX_PG_IMPLEMENT_EDITOR_CLASS(MultiButtonTextCtrlEditor, wxMultiButtonTextCtrlEditor,
- wxPGTextCtrlEditor)
+ wxIMPLEMENT_DYNAMIC_CLASS(wxSampleMultiButtonEditor, wxPGTextCtrlEditor);
- wxPGWindowList wxMultiButtonTextCtrlEditor::CreateControls( wxPropertyGrid* propGrid,
- wxPGProperty* property,
- const wxPoint& pos,
- const wxSize& sz ) const
+ wxPGWindowList wxSampleMultiButtonEditor::CreateControls( wxPropertyGrid* propGrid,
+ wxPGProperty* property,
+ const wxPoint& pos,
+ const wxSize& sz ) const
{
// Create and populate buttons-subwindow
wxPGMultiButton* buttons = new wxPGMultiButton( propGrid, sz );
// Create the 'primary' editor control (textctrl in this case)
wxPGWindowList wndList = wxPGTextCtrlEditor::CreateControls
- ( propGrid, property, pos, buttons->GetPrimarySize() );
+ ( propGrid, property, pos,
+ buttons->GetPrimarySize() );
// Finally, move buttons-subwindow to correct position and make sure
// returned wxPGWindowList contains our custom button list.
- buttons->FinalizePosition(pos);
+ buttons->Finalize(propGrid, pos);
wndList.SetSecondary( buttons );
return wndList;
}
- bool wxMultiButtonTextCtrlEditor::OnEvent( wxPropertyGrid* propGrid,
- wxPGProperty* property,
- wxWindow* ctrl,
- wxEvent& event ) const
+ bool wxSampleMultiButtonEditor::OnEvent( wxPropertyGrid* propGrid,
+ wxPGProperty* property,
+ wxWindow* ctrl,
+ wxEvent& event ) const
{
if ( event.GetEventType() == wxEVT_COMMAND_BUTTON_CLICKED )
{
if ( event.GetId() == buttons->GetButtonId(0) )
{
- // Do something when first button is pressed
- return true;
+ // Do something when the first button is pressed
+ // Return true if the action modified the value in editor.
+ ...
}
if ( event.GetId() == buttons->GetButtonId(1) )
{
- // Do something when first button is pressed
- return true;
+ // Do something when the second button is pressed
+ ...
}
if ( event.GetId() == buttons->GetButtonId(2) )
{
- // Do something when second button is pressed
- return true;
+ // Do something when the third button is pressed
+ ...
}
}
return wxPGTextCtrlEditor::OnEvent(propGrid, property, ctrl, event);
}
-
@endcode
Further to use this editor, code like this can be used:
@code
-
// Register editor class - needs only to be called once
- wxPGRegisterEditorClass( MultiButtonTextCtrlEditor );
+ wxPGEditor* multiButtonEditor = new wxSampleMultiButtonEditor();
+ wxPropertyGrid::RegisterEditorClass( multiButtonEditor );
// Insert the property that will have multiple buttons
propGrid->Append( new wxLongStringProperty("MultipleButtons", wxPG_LABEL) );
// Change property to use editor created in the previous code segment
- propGrid->SetPropertyEditor( "MultipleButtons", wxPG_EDITOR(MultiButtonTextCtrlEditor) );
-
+ propGrid->SetPropertyEditor( "MultipleButtons", multiButtonEditor );
@endcode
@library{wxpropgrid}
class WXDLLIMPEXP_PROPGRID wxPGMultiButton : public wxWindow
{
public:
-
+ /**
+ Constructor.
+ */
wxPGMultiButton( wxPropertyGrid* pg, const wxSize& sz );
+ /**
+ Destructor.
+ */
virtual ~wxPGMultiButton() { }
- wxWindow* GetButton( unsigned int i ) { return (wxWindow*) m_buttons[i]; }
- const wxWindow* GetButton( unsigned int i ) const { return (const wxWindow*) m_buttons[i]; }
+ /**
+ Adds new button, with given label.
+ */
+ void Add( const wxString& label, int id = -2 );
- /** Utility function to be used in event handlers.
+ /**
+ Adds new bitmap button.
*/
- int GetButtonId( unsigned int i ) const { return GetButton(i)->GetId(); }
+ void Add( const wxBitmap& bitmap, int id = -2 );
+
+ /**
+ Call this in CreateControls() of your custom editor class
+ after all buttons have been added.
+
+ @param propGrid
+ wxPropertyGrid given in CreateControls().
- /** Returns number of buttons.
+ @param pos
+ wxPoint given in CreateControls().
*/
- int GetCount() const { return m_buttons.Count(); }
+ void Finalize( wxPropertyGrid* propGrid, const wxPoint& pos );
- void Add( const wxString& label, int id = -2 );
- void Add( const wxBitmap& bitmap, int id = -2 );
+ /**
+ Returns pointer to one of the buttons.
+ */
+ wxWindow* GetButton( unsigned int i );
- wxSize GetPrimarySize() const
- {
- return wxSize(m_fullEditorSize.x - m_buttonsWidth, m_fullEditorSize.y);
- }
+ /**
+ Returns Id of one of the buttons.
+ This is utility function to be used in event handlers.
+ */
+ int GetButtonId( unsigned int i ) const;
- void FinalizePosition( const wxPoint& pos )
- {
- Move( pos.x + m_fullEditorSize.x - m_buttonsWidth, pos.y );
- }
-};
+ /**
+ Returns number of buttons.
+ */
+ unsigned int GetCount();
-// -----------------------------------------------------------------------
+ /**
+ Returns size of primary editor control, as appropriately
+ reduced by number of buttons present.
+ */
+ wxSize GetPrimarySize() const;
+};
-#endif // _WX_PROPGRID_EDITORS_H_
projects / wxWidgets.git / blobdiff