interface/wx/propgrid/editors.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        editors.h
   3 // Purpose:     interface of wxPropertyGrid editors
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id:
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 // -----------------------------------------------------------------------
  10
  11 /** @class wxPGEditor
  12
  13     Base class for custom wxPropertyGrid editors.
  14
  15     @remarks
  16     - Names of builtin property editors are: TextCtrl, Choice,
  17       ComboBox, CheckBox, TextCtrlAndButton, and ChoiceAndButton. Additional editors
  18       include SpinCtrl and DatePickerCtrl, but using them requires calling
  19       wxPropertyGrid::RegisterAdditionalEditors() prior use.
  20
  21     - Pointer to builtin editor is available as wxPGEditor_EditorName
  22       (eg. wxPGEditor_TextCtrl).
  23
  24     - To add new editor you need to register it first using static function
  25       wxPropertyGrid::RegisterEditorClass(), with code like this:
  26         @code
  27             wxPGEditor* editorPointer = wxPropertyGrid::RegisterEditorClass(new MyEditorClass(), "MyEditor");
  28         @endcode
  29       After that, wxPropertyGrid will take ownership of the given object, but
  30       you should still store editorPointer somewhere, so you can pass it to
  31       wxPGProperty::SetEditor(), or return it from wxPGEditor::DoGetEditorClass().
  32
  33     @library{wxpropgrid}
  34     @category{propgrid}
  35 */
  36 class wxPGEditor : public wxObject
  37 {
  38 public:
  39
  40     /** Constructor. */
  41     wxPGEditor()
  42         : wxObject()
  43     {
  44         m_clientData = NULL;
  45     }
  46
  47     /** Destructor. */
  48     virtual ~wxPGEditor();
  49
  50     /** Returns pointer to the name of the editor. For example, wxPG_EDITOR(TextCtrl)
  51         has name "TextCtrl". This method is autogenerated for custom editors.
  52     */
  53     virtual wxString GetName() const = 0;
  54
  55     /** Instantiates editor controls.
  56         @param propgrid
  57         wxPropertyGrid to which the property belongs (use as parent for control).
  58         @param property
  59         Property for which this method is called.
  60         @param pos
  61         Position, inside wxPropertyGrid, to create control(s) to.
  62         @param size
  63         Initial size for control(s).
  64
  65         @remarks
  66         - Primary control shall use id wxPG_SUBID1, and secondary (button) control
  67           shall use wxPG_SUBID2.
  68         - Implementation shoud connect all necessary events to the
  69           wxPropertyGrid::OnCustomEditorEvent. For Example:
  70             @code
  71                 // Relays wxEVT_COMMAND_TEXT_UPDATED events of primary editor
  72                 // control to the OnEvent.
  73                 propgrid->Connect(control->GetId(), wxEVT_COMMAND_TEXT_UPDATED,
  74                                   wxCommandEventHandler(wxPropertyGrid::OnCustomEditorEvent));
  75             @endcode
  76           OnCustomEditorEvent will then forward events, first to
  77           wxPGEditor::OnEvent() and then to wxPGProperty::OnEvent().
  78     */
  79     virtual wxPGWindowList CreateControls( wxPropertyGrid* propgrid, wxPGProperty* property,
  80         const wxPoint& pos, const wxSize& size ) const = 0;
  81
  82     /** Loads value from property to the control. */
  83     virtual void UpdateControl( wxPGProperty* property, wxWindow* ctrl ) const = 0;
  84
  85     /** Draws value for given property.
  86     */
  87     virtual void DrawValue( wxDC& dc, const wxRect& rect, wxPGProperty* property, const wxString& text ) const;
  88
  89     /** Handles events. Returns true if value in control was modified
  90         (see wxPGProperty::OnEvent for more information).
  91     */
  92     virtual bool OnEvent( wxPropertyGrid* propgrid, wxPGProperty* property,
  93         wxWindow* wnd_primary, wxEvent& event ) const = 0;
  94
  95     /** Returns value from control, via parameter 'variant'.
  96         Usually ends up calling property's StringToValue or IntToValue.
  97         Returns true if value was different.
  98     */
  99     virtual bool GetValueFromControl( wxVariant& variant, wxPGProperty* property, wxWindow* ctrl ) const;
 100
 101     /** Sets value in control to unspecified. */
 102     virtual void SetValueToUnspecified( wxPGProperty* property, wxWindow* ctrl ) const = 0;
 103
 104     /** Sets control's value specifically from string. */
 105     virtual void SetControlStringValue( wxPGProperty* property, wxWindow* ctrl, const wxString& txt ) const;
 106
 107     /** Sets control's value specifically from int (applies to choice etc.). */
 108     virtual void SetControlIntValue( wxPGProperty* property, wxWindow* ctrl, int value ) const;
 109
 110     /** Inserts item to existing control. Index -1 means appending.
 111         Default implementation does nothing. Returns index of item added.
 112     */
 113     virtual int InsertItem( wxWindow* ctrl, const wxString& label, int index ) const;
 114
 115     /** Deletes item from existing control.
 116         Default implementation does nothing.
 117     */
 118     virtual void DeleteItem( wxWindow* ctrl, int index ) const;
 119
 120     /** Extra processing when control gains focus. For example, wxTextCtrl
 121         based controls should select all text.
 122     */
 123     virtual void OnFocus( wxPGProperty* property, wxWindow* wnd ) const;
 124
 125     /** Returns true if control itself can contain the custom image. Default is
 126         to return false.
 127     */
 128     virtual bool CanContainCustomImage() const;
 129
 130     //
 131     // This member is public so scripting language bindings
 132     // wrapper code can access it freely.
 133     void*       m_clientData;
 134 };
 135
 136 // -----------------------------------------------------------------------
 137
 138 /** @class wxPGMultiButton
 139
 140     This class can be used to have multiple buttons in a property editor.
 141     You will need to create a new property editor class, override CreateControls,
 142     and have it return wxPGMultiButton instance in wxPGWindowList::SetSecondary().
 143     For instance, here we add three buttons to a textctrl editor:
 144
 145     @code
 146
 147     #include <wx/propgrid/editors.h>
 148
 149     class wxMultiButtonTextCtrlEditor : public wxPGTextCtrlEditor
 150     {
 151         WX_PG_DECLARE_EDITOR_CLASS(wxMultiButtonTextCtrlEditor)
 152     public:
 153         wxMultiButtonTextCtrlEditor() {}
 154         virtual ~wxMultiButtonTextCtrlEditor() {}
 155
 156         wxPG_DECLARE_CREATECONTROLS
 157         virtual bool OnEvent( wxPropertyGrid* propGrid,
 158                               wxPGProperty* property,
 159                               wxWindow* ctrl,
 160                               wxEvent& event ) const;
 161
 162     };
 163
 164     WX_PG_IMPLEMENT_EDITOR_CLASS(MultiButtonTextCtrlEditor, wxMultiButtonTextCtrlEditor,
 165                                  wxPGTextCtrlEditor)
 166
 167     wxPGWindowList wxMultiButtonTextCtrlEditor::CreateControls( wxPropertyGrid* propGrid,
 168                                                                 wxPGProperty* property,
 169                                                                 const wxPoint& pos,
 170                                                                 const wxSize& sz ) const
 171     {
 172         // Create and populate buttons-subwindow
 173         wxPGMultiButton* buttons = new wxPGMultiButton( propGrid, sz );
 174
 175         // Add two regular buttons
 176         buttons->Add( "..." );
 177         buttons->Add( "A" );
 178         // Add a bitmap button
 179         buttons->Add( wxArtProvider::GetBitmap(wxART_FOLDER) );
 180
 181         // Create the 'primary' editor control (textctrl in this case)
 182         wxPGWindowList wndList = wxPGTextCtrlEditor::CreateControls
 183                                  ( propGrid, property, pos, buttons->GetPrimarySize() );
 184
 185         // Finally, move buttons-subwindow to correct position and make sure
 186         // returned wxPGWindowList contains our custom button list.
 187         buttons->FinalizePosition(pos);
 188
 189         wndList.SetSecondary( buttons );
 190         return wndList;
 191     }
 192
 193     bool wxMultiButtonTextCtrlEditor::OnEvent( wxPropertyGrid* propGrid,
 194                                                wxPGProperty* property,
 195                                                wxWindow* ctrl,
 196                                                wxEvent& event ) const
 197     {
 198         if ( event.GetEventType() == wxEVT_COMMAND_BUTTON_CLICKED )
 199         {
 200             wxPGMultiButton* buttons = (wxPGMultiButton*) propGrid->GetEditorControlSecondary();
 201
 202             if ( event.GetId() == buttons->GetButtonId(0) )
 203             {
 204                 // Do something when first button is pressed
 205                 return true;
 206             }
 207             if ( event.GetId() == buttons->GetButtonId(1) )
 208             {
 209                 // Do something when first button is pressed
 210                 return true;
 211             }
 212             if ( event.GetId() == buttons->GetButtonId(2) )
 213             {
 214                 // Do something when second button is pressed
 215                 return true;
 216             }
 217         }
 218         return wxPGTextCtrlEditor::OnEvent(propGrid, property, ctrl, event);
 219     }
 220
 221     @endcode
 222
 223     Further to use this editor, code like this can be used:
 224
 225     @code
 226
 227         // Register editor class - needs only to be called once
 228         wxPGRegisterEditorClass( MultiButtonTextCtrlEditor );
 229
 230         // Insert the property that will have multiple buttons
 231         propGrid->Append( new wxLongStringProperty("MultipleButtons", wxPG_LABEL) );
 232
 233         // Change property to use editor created in the previous code segment
 234         propGrid->SetPropertyEditor( "MultipleButtons", wxPG_EDITOR(MultiButtonTextCtrlEditor) );
 235
 236     @endcode
 237
 238     @library{wxpropgrid}
 239     @category{propgrid}
 240 */
 241 class WXDLLIMPEXP_PROPGRID wxPGMultiButton : public wxWindow
 242 {
 243 public:
 244
 245     wxPGMultiButton( wxPropertyGrid* pg, const wxSize& sz );
 246
 247     virtual ~wxPGMultiButton() { }
 248
 249     wxWindow* GetButton( unsigned int i ) { return (wxWindow*) m_buttons[i]; }
 250     const wxWindow* GetButton( unsigned int i ) const { return (const wxWindow*) m_buttons[i]; }
 251
 252     /** Utility function to be used in event handlers.
 253     */
 254     int GetButtonId( unsigned int i ) const { return GetButton(i)->GetId(); }
 255
 256     /** Returns number of buttons.
 257     */
 258     int GetCount() const { return m_buttons.Count(); }
 259
 260     void Add( const wxString& label, int id = -2 );
 261     void Add( const wxBitmap& bitmap, int id = -2 );
 262
 263     wxSize GetPrimarySize() const
 264     {
 265         return wxSize(m_fullEditorSize.x - m_buttonsWidth, m_fullEditorSize.y);
 266     }
 267
 268     void FinalizePosition( const wxPoint& pos )
 269     {
 270         Move( pos.x + m_fullEditorSize.x - m_buttonsWidth, pos.y );
 271     }
 272 };
 273
 274 // -----------------------------------------------------------------------
 275
 276 #endif // _WX_PROPGRID_EDITORS_H_