X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/23324ae1c7938ba904770fc456d3c07764b9c5e9..491a5ece423db6de431d0533f142d25996e9483b:/interface/html/htmlcell.h diff --git a/interface/html/htmlcell.h b/interface/html/htmlcell.h index 9fed378057..d4127f8b29 100644 --- a/interface/html/htmlcell.h +++ b/interface/html/htmlcell.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: html/htmlcell.h -// Purpose: documentation for wxHtmlColourCell class +// Purpose: interface of wxHtmlColourCell // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -9,9 +9,9 @@ /** @class wxHtmlColourCell @headerfile htmlcell.h wx/html/htmlcell.h - - This cell changes the colour of either the background or the foreground. - + + This cell changes the colour of either the background or the foreground. + @library{wxhtml} @category{FIXME} */ @@ -21,37 +21,50 @@ public: /** Constructor. - @param clr - The color + @param clr + The color + @param flags + Can be one of following: + + + + + + + wxHTML_CLR_FOREGROUND + + - @param flags - Can be one of following: - wxHTML_CLR_FOREGROUND + change color of text - change color of text - wxHTML_CLR_BACKGROUND - change background color + wxHTML_CLR_BACKGROUND + + + + + change background color */ wxHtmlColourCell(wxColour clr, int flags = wxHTML_CLR_FOREGROUND); }; + /** @class wxHtmlWidgetCell @headerfile htmlcell.h wx/html/htmlcell.h - + wxHtmlWidgetCell is a class that provides a connection between HTML cells and widgets (an object derived from wxWindow). You can use it to display things like forms, input boxes etc. in an HTML window. - + wxHtmlWidgetCell takes care of resizing and moving window. - + @library{wxhtml} @category{FIXME} */ @@ -61,38 +74,37 @@ public: /** Constructor. - @param wnd - Connected window. It is parent window must be the wxHtmlWindow object within - which it is displayed! - - @param w - Floating width. If non-zero width of wnd window is adjusted so that it is - always w percents of parent container's width. (For example w = 100 means that - the window - will always have same width as parent container) + @param wnd + Connected window. It is parent window must be the wxHtmlWindow object within + which it is displayed! + @param w + Floating width. If non-zero width of wnd window is adjusted so that it is + always w percents of parent container's width. (For example w = 100 means + that the window + will always have same width as parent container) */ wxHtmlWidgetCell(wxWindow* wnd, int w = 0); }; + /** @class wxHtmlCell @headerfile htmlcell.h wx/html/htmlcell.h - + Internal data structure. It represents fragments of parsed HTML page, the so-called @b cell - a word, picture, table, horizontal line and so on. - It is used by wxHtmlWindow and + It is used by wxHtmlWindow and wxHtmlWinParser to represent HTML page in memory. - + You can divide cells into two groups : @e visible cells with non-zero width and height and @e helper cells (usually with zero width and height) that perform special actions such as color or font change. - + @library{wxhtml} @category{FIXME} - - @seealso - @ref overview_cells "Cells Overview", wxHtmlContainerCell + + @see @ref overview_cells "Cells Overview", wxHtmlContainerCell */ class wxHtmlCell : public wxObject { @@ -108,31 +120,26 @@ public: should not be crossed by words, images etc.). If this cell cannot be divided into two pieces (each one on another page) then it moves the pagebreak few pixels up. - Returns @true if pagebreak was modified, @false otherwise - Usage: */ - virtual bool AdjustPagebreak(int * pagebreak); + virtual bool AdjustPagebreak(int* pagebreak); /** Renders the cell. - @param dc - Device context to which the cell is to be drawn - - @param x,y - Coordinates of parent's upper left corner (origin). You must - add this to m_PosX,m_PosY when passing coordinates to dc's methods - Example : dc - DrawText("hello", x + m_PosX, y + m_PosY) - - @param view_y1 - y-coord of the first line visible in window. This is - used to optimize rendering speed - - @param view_y2 - y-coord of the last line visible in window. This is - used to optimize rendering speed + @param dc + Device context to which the cell is to be drawn + @param x,y + Coordinates of parent's upper left corner (origin). You must + add this to m_PosX,m_PosY when passing coordinates to dc's methods + Example : dc - DrawText("hello", x + m_PosX, y + m_PosY) + @param view_y1 + y-coord of the first line visible in window. This is + used to optimize rendering speed + @param view_y2 + y-coord of the last line visible in window. This is + used to optimize rendering speed */ virtual void Draw(wxDC& dc, int x, int y, int view_y1, int view_y2); @@ -143,13 +150,12 @@ public: nonsense - some tags (like wxHtmlColourCell or font setter) must be drawn even if they are invisible! - @param dc - Device context to which the cell is to be drawn - - @param x,y - Coordinates of parent's upper left corner. You must - add this to m_PosX,m_PosY when passing coordinates to dc's methods - Example : dc - DrawText("hello", x + m_PosX, y + m_PosY) + @param dc + Device context to which the cell is to be drawn + @param x,y + Coordinates of parent's upper left corner. You must + add this to m_PosX,m_PosY when passing coordinates to dc's methods + Example : dc - DrawText("hello", x + m_PosX, y + m_PosY) */ virtual void DrawInvisible(wxDC& dc, int x, int y); @@ -158,30 +164,27 @@ public: following in the list matches), @NULL otherwise. (In other words if you call top-level container's Find it will return pointer to the first cell that matches the condition) - It is recommended way how to obtain pointer to particular cell or to cell of some type (e.g. wxHtmlAnchorCell reacts on wxHTML_COND_ISANCHOR condition) - @param condition - Unique integer identifier of condition - - @param param - Optional parameters + @param condition + Unique integer identifier of condition + @param param + Optional parameters */ virtual const wxHtmlCell* Find(int condition, const void* param); /** - Returns descent value of the cell (m_Descent member). + Returns descent value of the cell (m_Descent member). See explanation: */ - int GetDescent(); + int GetDescent() const; /** Returns pointer to the first cell in the list. You can then use child's GetNext() method to obtain pointer to the next cell in list. - @b Note: This shouldn't be used by the end user. If you need some way of finding particular cell in the list, try Find() method instead. @@ -191,30 +194,30 @@ public: /** Returns height of the cell (m_Height member). */ - int GetHeight(); + int GetHeight() const; /** Returns unique cell identifier if there is any, empty string otherwise. */ - virtual wxString GetId(); + virtual wxString GetId() const; /** Returns hypertext link if associated with this cell or @NULL otherwise. See wxHtmlLinkInfo. (Note: this makes sense only for visible tags). - @param x,y - Coordinates of position where the user pressed mouse button. - These coordinates are used e.g. by COLORMAP. Values are relative to the - upper left corner of THIS cell (i.e. from 0 to m_Width or m_Height) + @param x,y + Coordinates of position where the user pressed mouse button. + These coordinates are used e.g. by COLORMAP. Values are relative to the + upper left corner of THIS cell (i.e. from 0 to m_Width or m_Height) */ - virtual wxHtmlLinkInfo* GetLink(int x = 0, int y = 0); + virtual wxHtmlLinkInfo* GetLink(int x = 0, int y = 0) const; /** Returns cursor to show when mouse pointer is over the cell. - @param window - interface to the parent HTML window + @param window + interface to the parent HTML window */ virtual wxCursor GetMouseCursor(wxHtmlWindowInterface* window); @@ -222,41 +225,39 @@ public: Returns pointer to the next cell in list (see htmlcell.h if you're interested in details). */ - wxHtmlCell* GetNext(); + wxHtmlCell* GetNext() const; /** Returns pointer to parent container. */ - wxHtmlContainerCell* GetParent(); + wxHtmlContainerCell* GetParent() const; /** Returns X position within parent (the value is relative to parent's upper left corner). The returned value is meaningful only if parent's Layout() was called before! */ - int GetPosX(); + int GetPosX() const; /** Returns Y position within parent (the value is relative to parent's upper left corner). The returned value is meaningful only if parent's Layout() was called before! */ - int GetPosY(); + int GetPosY() const; /** Returns width of the cell (m_Width member). */ - int GetWidth(); + int GetWidth() const; /** This method performs two actions: - adjusts the cell's width according to the fact that maximal possible width is @e w. (this has sense when working with horizontal lines, tables etc.) prepares layout (=fill-in m_PosX, m_PosY (and sometimes m_Height) members) based on actual width @e w - It must be called before displaying cells structure because m_PosX and m_PosY are undefined (or invalid) before calling Layout. @@ -269,14 +270,12 @@ public: cell is called. Default behavior is to call wxHtmlWindow::LoadPage. - @param window - interface to the parent HTML window - - @param pos - coordinates of mouse click (this is relative to cell's origin - - @param event - mouse event that triggered the call + @param window + interface to the parent HTML window + @param pos + coordinates of mouse click (this is relative to cell's origin + @param event + mouse event that triggered the call @returns @true if a link was clicked, @false otherwise. */ @@ -314,36 +313,36 @@ public: }; + /** @class wxHtmlContainerCell @headerfile htmlcell.h wx/html/htmlcell.h - + The wxHtmlContainerCell class is an implementation of a cell that may contain more cells in it. It is heavily used in the wxHTML layout algorithm. - + @library{wxhtml} @category{FIXME} - - @seealso - @ref overview_cells "Cells Overview" + + @see @ref overview_cells "Cells Overview" */ class wxHtmlContainerCell : public wxHtmlCell { public: /** - Constructor. @e parent is pointer to parent container or @NULL. + Constructor. @a parent is pointer to parent container or @NULL. */ wxHtmlContainerCell(wxHtmlContainerCell parent); /** Returns container's horizontal alignment. */ - int GetAlignHor(); + int GetAlignHor() const; /** Returns container's vertical alignment. */ - int GetAlignVer(); + int GetAlignVer() const; /** Returns the background colour of the container or @c wxNullColour if no @@ -353,20 +352,19 @@ public: wxColour GetBackgroundColour(); /** - Returns the indentation. @e ind is one of the @b wxHTML_INDENT_* constants. - - @b Note: You must call GetIndentUnits() - with same @e ind parameter in order to correctly interpret the returned integer + Returns the indentation. @a ind is one of the @b wxHTML_INDENT_* constants. + @b Note: You must call GetIndentUnits() + with same @a ind parameter in order to correctly interpret the returned integer value. It is NOT always in pixels! */ - int GetIndent(int ind); + int GetIndent(int ind) const; /** - Returns the units of indentation for @e ind where @e ind is one + Returns the units of indentation for @a ind where @a ind is one of the @b wxHTML_INDENT_* constants. */ - int GetIndentUnits(int ind); + int GetIndentUnits(int ind) const; /** Inserts new cell into the container. @@ -376,60 +374,104 @@ public: /** Sets the container's alignment (both horizontal and vertical) according to the values stored in @e tag. (Tags @c ALIGN parameter is extracted.) In fact - it is only a front-end to SetAlignHor() + it is only a front-end to SetAlignHor() and SetAlignVer(). */ void SetAlign(const wxHtmlTag& tag); /** - Sets the container's @e horizontal alignment. During wxHtmlCell::Layout - each line is aligned according to @e al value. + Sets the container's @e horizontal alignment. During wxHtmlCell::Layout + each line is aligned according to @a al value. + + @param al + new horizontal alignment. May be one of these values: + + + + + + + wxHTML_ALIGN_LEFT + + + + + lines are left-aligned (default) + + + + + + wxHTML_ALIGN_JUSTIFY + + - @param al - new horizontal alignment. May be one of these values: - wxHTML_ALIGN_LEFT + lines are justified - lines are left-aligned (default) - wxHTML_ALIGN_JUSTIFY - lines are justified + wxHTML_ALIGN_CENTER - wxHTML_ALIGN_CENTER - lines are centered - wxHTML_ALIGN_RIGHT + lines are centered - lines are right-aligned + + + + wxHTML_ALIGN_RIGHT + + + + + lines are right-aligned */ void SetAlignHor(int al); /** Sets the container's @e vertical alignment. This is per-line alignment! - @param al - new vertical alignment. May be one of these values: + @param al + new vertical alignment. May be one of these values: + + + + + + + wxHTML_ALIGN_BOTTOM + + + + + cells are over the line (default) + + - wxHTML_ALIGN_BOTTOM - cells are over the line (default) + wxHTML_ALIGN_CENTER - wxHTML_ALIGN_CENTER - cells are centered on line - wxHTML_ALIGN_TOP + cells are centered on line - cells are under the line + + + + wxHTML_ALIGN_TOP + + + + + cells are under the line */ void SetAlignVer(int al); @@ -441,149 +483,210 @@ public: /** Sets the border (frame) colours. A border is a rectangle around the container. - @param clr1 - Colour of top and left lines - - @param clr2 - Colour of bottom and right lines + @param clr1 + Colour of top and left lines + @param clr2 + Colour of bottom and right lines */ void SetBorder(const wxColour& clr1, const wxColour& clr2); /** Sets the indentation (free space between borders of container and subcells). - @param i - Indentation value. + @param i + Indentation value. + @param what + Determines which of the four borders we're setting. It is OR + combination of following constants: + + + + + + + wxHTML_INDENT_TOP + + + + + top border + + + + + + wxHTML_INDENT_BOTTOM + + + + + bottom + + + + + + wxHTML_INDENT_LEFT + + + + + left + + + - @param what - Determines which of the four borders we're setting. It is OR - combination of following constants: - wxHTML_INDENT_TOP + wxHTML_INDENT_RIGHT - top border - wxHTML_INDENT_BOTTOM + right - bottom - wxHTML_INDENT_LEFT - left - wxHTML_INDENT_RIGHT + wxHTML_INDENT_HORIZONTAL - right - wxHTML_INDENT_HORIZONTAL + left and right - left and right - wxHTML_INDENT_VERTICAL - top and bottom - wxHTML_INDENT_ALL + wxHTML_INDENT_VERTICAL - all 4 borders - @param units - Units of i. This parameter affects interpretation of value. + top and bottom - wxHTML_UNITS_PIXELS - i is number of pixels - wxHTML_UNITS_PERCENT + wxHTML_INDENT_ALL - i is interpreted as percents of width - of parent container + + + + all 4 borders + @param units + Units of i. This parameter affects interpretation of value. + + + + + + + wxHTML_UNITS_PIXELS + + + + + i is number of pixels + + + + + + wxHTML_UNITS_PERCENT + + + + + i is interpreted as percents of width + of parent container */ void SetIndent(int i, int what, int units = wxHTML_UNITS_PIXELS); /** Sets minimal height of the container. - When container's wxHtmlCell::Layout is called, m_Height is set depending on layout of subcells to the height of area covered by layed-out subcells. Calling this method guarantees you that the height - of container is never smaller than @e h - even if the subcells cover + of container is never smaller than @a h - even if the subcells cover much smaller area. - @param h - The minimal height. - - @param align - If height of the container is lower than the minimum height, empty space must - be inserted - somewhere in order to ensure minimal height. This parameter is one of + @param h + The minimal height. + @param align + If height of the container is lower than the minimum height, empty space + must be inserted + somewhere in order to ensure minimal height. This parameter is one of wxHTML_ALIGN_TOP, - wxHTML_ALIGN_BOTTOM, wxHTML_ALIGN_CENTER. It refers to the contents, not to the - empty place. + wxHTML_ALIGN_BOTTOM, wxHTML_ALIGN_CENTER. It refers to the contents, not to + the + empty place. */ void SetMinHeight(int h, int align = wxHTML_ALIGN_TOP); //@{ /** Sets floating width adjustment. - The normal behaviour of container is that its width is the same as the width of parent container (and thus you can have only one sub-container per line). You can change this by setting FWA. + @a pixel_scale is number of real pixels that equals to 1 HTML pixel. + + @param w + Width of the container. If the value is negative it means + complement to full width of parent container (e.g. + SetWidthFloat(-50, wxHTML_UNITS_PIXELS) sets the width + of container to parent's width minus 50 pixels. This is useful when + creating tables - you can call SetWidthFloat(50) and SetWidthFloat(-50)) + @param units + Units of w This parameter affects the interpretation of value. + + + + - @e pixel_scale is number of real pixels that equals to 1 HTML pixel. - @param w - Width of the container. If the value is negative it means - complement to full width of parent container (e.g. - SetWidthFloat(-50, wxHTML_UNITS_PIXELS) sets the width - of container to parent's width minus 50 pixels. This is useful when - creating tables - you can call SetWidthFloat(50) and SetWidthFloat(-50)) + wxHTML_UNITS_PIXELS - @param units - Units of w This parameter affects the interpretation of value. - wxHTML_UNITS_PIXELS - w is number of pixels + w is number of pixels - wxHTML_UNITS_PERCENT - w is interpreted as percents of width - of parent container - @param tag - In the second version of method, w and units - info is extracted from tag's WIDTH parameter. + + wxHTML_UNITS_PERCENT + + + + + w is interpreted as percents of width + of parent container + @param tag + In the second version of method, w and units + info is extracted from tag's WIDTH parameter. */ void SetWidthFloat(int w, int units); - void SetWidthFloat(const wxHtmlTag& tag, - double pixel_scale = 1.0); + void SetWidthFloat(const wxHtmlTag& tag, + double pixel_scale = 1.0); //@} }; + /** @class wxHtmlLinkInfo @headerfile htmlcell.h wx/html/htmlcell.h - + This class stores all necessary information about hypertext - links (as represented by @c A tag in HTML documents). In - current implementation it stores URL and target frame name. + links (as represented by @c A tag in HTML documents). In + current implementation it stores URL and target frame name. @e Note that frames are not currently supported by wxHTML! - + @library{wxhtml} @category{FIXME} */ @@ -596,8 +699,8 @@ public: frame). */ wxHtmlLinkInfo(); - wxHtmlLinkInfo(const wxString& href, - const wxString& target = wxEmptyString); + wxHtmlLinkInfo(const wxString& href, + const wxString& target = wxEmptyString); //@} /** @@ -605,7 +708,7 @@ public: only within wxHtmlWindow::OnLinkClicked, @NULL otherwise. */ - const wxMouseEvent * GetEvent(); + const wxMouseEvent* GetEvent(); /** Return @e HREF value of the @c A tag. @@ -617,7 +720,7 @@ public: only within wxHtmlWindow::OnLinkClicked, @NULL otherwise. */ - const wxHtmlCell * GetHtmlCell(); + const wxHtmlCell* GetHtmlCell(); /** Return @e TARGET value of the @c A tag (this value @@ -626,3 +729,4 @@ public: */ wxString GetTarget(); }; +