docs/latex/wx/odcbox.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        odcbox.tex
   3 %% Purpose:     wxOwnerDrawnComboBox docs
   4 %% Author:      Jaakko Salli
   5 %% Modified by:
   6 %% Created:
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) Jaakko Salli
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxOwnerDrawnComboBox}}\label{wxownerdrawncombobox}
  13
  14 wxOwnerDrawnComboBox is a combobox with owner-drawn list items.
  15 In essence, it is a \helpref{wxComboCtrl}{wxcomboctrl} with
  16 \helpref{wxVListBox}{wxvlistbox} popup and \helpref{wxControlWithItems}{wxcontrolwithitems}
  17 interface.
  18
  19 Implementing item drawing and measuring is similar to \helpref{wxVListBox}{wxvlistbox}.
  20 Application needs to subclass wxOwnerDrawnComboBox and implement
  21 \helpref{OnDrawItem()}{wxownerdrawncomboboxondrawitem}, \helpref{OnMeasureItem()}{wxownerdrawncomboboxonmeasureitem}
  22 and \helpref{OnMeasureItemWidth()}{wxownerdrawncomboboxonmeasureitemwidth}.
  23
  24
  25 \wxheading{Derived from}
  26
  27 \helpref{wxComboCtrl}{wxcomboctrl}\\
  28 \helpref{wxControlWithItems}{wxcontrolwithitems}\\
  29 \helpref{wxControl}{wxcontrol}\\
  30 \helpref{wxWindow}{wxwindow}\\
  31 \helpref{wxEvtHandler}{wxevthandler}\\
  32 \helpref{wxObject}{wxobject}
  33
  34 \wxheading{Include files}
  35
  36 <wx/odcombo.h>
  37
  38 \wxheading{Library}
  39
  40 \helpref{wxAdv}{librarieslist}
  41
  42 \wxheading{Window styles}
  43
  44 \begin{twocollist}\itemsep=0pt
  45 \twocolitem{\windowstyle{wxODCB\_DCLICK\_CYCLES}}{Double-clicking cycles item
  46 if wxCB\_READONLY is also used. Synonymous with wxCC\_SPECIAL\_DCLICK.}
  47 \twocolitem{\windowstyle{wxODCB\_STD\_CONTROL\_PAINT}}{Control itself is not
  48 custom painted using OnDrawItem. Even if this style is not used, writable
  49 wxOwnerDrawnComboBox is never custom painted unless SetCustomPaintWidth is
  50 called.}
  51 \end{twocollist}
  52
  53 See also \helpref{wxComboCtrl window styles}{wxcomboctrl} and
  54 base \helpref{window styles overview}{windowstyles}.
  55
  56 \wxheading{Event handling}
  57
  58 \twocolwidtha{7cm}
  59 \begin{twocollist}\itemsep=0pt
  60 \twocolitem{{\bf EVT\_COMBOBOX(id, func)}}{Process a wxEVT\_COMMAND\_COMBOBOX\_SELECTED event,
  61 when an item on the list is selected. Note that calling
  62 \helpref{GetValue}{wxcomboctrlgetvalue} returns the new value of selection.}
  63 \end{twocollist}
  64
  65 See also events emitted by \helpref{wxComboCtrl}{wxcomboctrl}.
  66
  67 \wxheading{See also}
  68
  69 \helpref{wxComboCtrl}{wxcomboctrl}, \helpref{wxComboBox}{wxcombobox}, \helpref{wxVListBox}{wxvlistbox},
  70 \rtfsp\helpref{wxCommandEvent}{wxcommandevent}
  71
  72
  73 \latexignore{\rtfignore{\wxheading{Members}}}
  74
  75
  76 \membersection{wxOwnerDrawnComboBox::wxOwnerDrawnComboBox}\label{wxownerdrawncomboboxctor}
  77
  78 \func{}{wxOwnerDrawnComboBox}{\void}
  79
  80 Default constructor.
  81
  82 \func{}{wxOwnerDrawnComboBox}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
  83 \param{const wxString\& }{value = ``"}, \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
  84 \param{int}{ n = 0}, \param{const wxString }{choices[] = NULL},\rtfsp
  85 \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
  86
  87 \func{}{wxOwnerDrawnComboBox}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
  88 \param{const wxString\& }{value}, \param{const wxPoint\&}{ pos}, \param{const wxSize\&}{ size},\rtfsp
  89 \param{const wxArrayString\& }{choices},\rtfsp
  90 \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
  91
  92 Constructor, creating and showing a owner-drawn combobox.
  93
  94 \wxheading{Parameters}
  95
  96 \docparam{parent}{Parent window. Must not be NULL.}
  97
  98 \docparam{id}{Window identifier. A value of -1 indicates a default value.}
  99
 100 \docparam{value}{Initial selection string. An empty string indicates no selection.}
 101
 102 \docparam{pos}{Window position.}
 103
 104 \docparam{size}{Window size. If the default size (-1, -1) is specified then the window is sized
 105 appropriately.}
 106
 107 \docparam{n}{Number of strings with which to initialise the control.}
 108
 109 \docparam{choices}{An array of strings with which to initialise the control.}
 110
 111 \docparam{style}{Window style. See \helpref{wxOwnerDrawnComboBox}{wxownerdrawncombobox}.}
 112
 113 \docparam{validator}{Window validator.}
 114
 115 \docparam{name}{Window name.}
 116
 117 \wxheading{See also}
 118
 119 \helpref{wxOwnerDrawnComboBox::Create}{wxownerdrawncomboboxcreate}, \helpref{wxValidator}{wxvalidator}
 120
 121
 122 \membersection{wxOwnerDrawnComboBox::\destruct{wxOwnerDrawnComboBox}}\label{wxownerdrawncomboboxdtor}
 123
 124 \func{}{\destruct{wxOwnerDrawnComboBox}}{\void}
 125
 126 Destructor, destroying the owner-drawn combobox.
 127
 128
 129 \membersection{wxOwnerDrawnComboBox::Create}\label{wxownerdrawncomboboxcreate}
 130
 131 \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
 132 \param{const wxString\& }{value = ``"}, \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
 133 \param{int}{ n}, \param{const wxString }{choices[]},\rtfsp
 134 \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
 135
 136 \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
 137 \param{const wxString\& }{value}, \param{const wxPoint\&}{ pos}, \param{const wxSize\&}{ size},\rtfsp
 138 \param{const wxArrayString\& }{choices},\rtfsp
 139 \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
 140
 141 Creates the combobox for two-step construction. Derived classes
 142 should call or replace this function. See
 143 \helpref{wxOwnerDrawnComboBox::wxOwnerDrawnComboBox}{wxownerdrawncomboboxctor}\rtfsp
 144 for further details.
 145
 146
 147 \membersection{wxOwnerDrawnComboBox::GetWidestItem}\label{wxownerdrawncomboboxgetwidestitem}
 148
 149 \constfunc{int}{GetWidestItem}{\void}
 150
 151 Returns index to the widest item in the list.
 152
 153
 154 \membersection{wxOwnerDrawnComboBox::GetWidestItemWidth}\label{wxownerdrawncomboboxgetwidestitemwidth}
 155
 156 \constfunc{int}{GetWidestItemWidth}{\void}
 157
 158 Returns width of the widest item in the list.
 159
 160
 161 \membersection{wxOwnerDrawnComboBox::OnDrawBackground}\label{wxownerdrawncomboboxondrawbackground}
 162
 163 \constfunc{void}{OnDrawBackground}{\param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{int }{item}, \param{int }{flags}}
 164
 165 This method is used to draw the items background and, maybe, a border around it.
 166
 167 The base class version implements a reasonable default behaviour which consists
 168 in drawing the selected item with the standard background colour and drawing a
 169 border around the item if it is either selected or current.
 170
 171 \wxheading{Remarks}
 172
 173 \arg{flags} has the same meaning as with \helpref{OnDrawItem}{wxownerdrawncomboboxondrawitem}.
 174
 175
 176 \membersection{wxOwnerDrawnComboBox::OnDrawItem}\label{wxownerdrawncomboboxondrawitem}
 177
 178 \constfunc{void}{OnDrawItem}{\param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{int }{item}, \param{int }{flags}}
 179
 180 The derived class may implement this function to actually draw the item
 181 with the given index on the provided DC. If function is not implemented,
 182 the item text is simply drawn, as if the control was a normal combobox.
 183
 184 \wxheading{Parameters}
 185
 186 \docparam{dc}{The device context to use for drawing}
 187
 188 \docparam{rect}{The bounding rectangle for the item being drawn (DC clipping
 189 region is set to this rectangle before calling this function)}
 190
 191 \docparam{item}{The index of the item to be drawn}
 192
 193 \docparam{flags}{Combines any of the following flag values:}
 194
 195 \twocolwidtha{7cm}%
 196 \begin{twocollist}\itemsep=0pt
 197 \twocolitem{{\tt wxODCB\_PAINTING\_CONTROL}}{Combo control is being
 198 painted, instead of a list item. Argument item may be wxNOT\_FOUND in this
 199 case.}
 200 \twocolitem{{\tt wxODCB\_PAINTING\_SELECTED}}{An item with selection
 201 background is being painted. DC text colour should already be correct.}
 202 \end{twocollist}
 203
 204
 205 \membersection{wxOwnerDrawnComboBox::OnMeasureItem}\label{wxownerdrawncomboboxonmeasureitem}
 206
 207 \constfunc{wxCoord}{OnMeasureItem}{\param{size\_t }{item}}
 208
 209 The derived class may implement this method to return the height of the
 210 specified item (in pixels).
 211
 212 The default implementation returns text height, as if this control was
 213 a normal combobox.
 214
 215
 216 \membersection{wxOwnerDrawnComboBox::OnMeasureItemWidth}\label{wxownerdrawncomboboxonmeasureitemwidth}
 217
 218 \constfunc{wxCoord}{OnMeasureItemWidth}{\param{size\_t }{item}}
 219
 220 The derived class may implement this method to return the width of the
 221 specified item (in pixels). If -1 is returned, then the item text width
 222 is used.
 223
 224 The default implementation returns -1.
 225