Lerking/Phoenix
1
0
Fork 0
mirror of https://github.com/wxWidgets/Phoenix.git synced 2026-01-06 20:10:08 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

A few more overview updates

Browse Source
This commit is contained in:
Robin Dunn
2016-05-27 23:59:15 -07:00
parent ea5c22317a
commit f4213cb076
4 changed files with 332 additions and 276 deletions
Download Patch File Download Diff File Expand all files Collapse all files

83
docs/sphinx/rest_substitutions/overviews/font_encodings.rst
View File

@@ -10,48 +10,67 @@
wxPython has support for multiple font encodings.
By encoding we mean here the mapping between the character codes and the letters. Probably the most well-known encoding is
(7 bit) ASCII one which is used almost universally now to represent the letters of the English alphabet and some other
common characters. However, it is not enough to represent the letters of foreign alphabets and here other encodings
come into play. Please note that we will only discuss 8-bit fonts here and not Unicode.
By encoding we mean here the mapping between the character codes and
the letters. Probably the most well-known encoding is (7 bit) ASCII
one which is used almost universally now to represent the letters of
the English alphabet and some other common characters. However, it is
not enough to represent the letters of foreign alphabets and here
other encodings come into play. Please note that we will only discuss
8-bit fonts here and not Unicode.
Font encoding support is ensured by several classes: :ref:`Font` itself, but also :ref:`FontEnumerator` and :ref:`FontMapper`.
:ref:`Font` encoding support is reflected by a (new) constructor parameter encoding which takes one of the following
values (elements of enumeration type :ref:`FontEncoding`):
Font encoding support is ensured by several classes: :ref:`Font`
itself, but also :ref:`wx.FontEnumerator`
and :ref:`wx.FontMapper`. :ref:`wx.Font` encoding support is reflected by a
(new) constructor parameter encoding which takes one of the following
values (elements of enumeration type :ref:`wx.FontEncoding`):
======================================== =========================================================
``FONTENCODING_SYSTEM`` The default encoding of the underlying operating system (notice that this might be a "foreign" encoding for foreign versions of Windows 9x/NT).
``FONTENCODING_DEFAULT`` The applications default encoding as returned by :meth:`Font.GetDefaultEncoding`. On program startup, the applications default encoding is the same as ``FONTENCODING_SYSTEM``, but may be changed to make all the fonts created later to use it (by default).
``FONTENCODING_ISO8859_1..15`` ISO8859 family encodings which are usually used by all non-Microsoft operating systems.
``FONTENCODING_KOI8`` Standard Cyrillic encoding for the Internet (but see also ``FONTENCODING_ISO8859_5`` and ``FONTENCODING_CP1251``).
``FONTENCODING_CP1250`` Microsoft analogue of ISO8859-2
``FONTENCODING_CP1251`` Microsoft analogue of ISO8859-5
``FONTENCODING_CP1252`` Microsoft analogue of ISO8859-1
``wx.FONTENCODING_SYSTEM`` The default encoding of the underlying operating system (notice that this might be a "foreign" encoding for foreign versions of Windows 9x/NT).
``wx.FONTENCODING_DEFAULT`` The applications default encoding as returned by :meth:`wx.Font.GetDefaultEncoding`. On program startup, the applications default encoding is the same as ``wx.FONTENCODING_SYSTEM``, but may be changed to make all the fonts created later to use it (by default).
``wx.FONTENCODING_ISO8859_1..15`` ISO8859 family encodings which are usually used by all non-Microsoft operating systems.
``wx.FONTENCODING_KOI8`` Standard Cyrillic encoding for the Internet (but see also ``wx.FONTENCODING_ISO8859_5`` and ``wx.FONTENCODING_CP1251``).
``wx.FONTENCODING_CP1250`` Microsoft analogue of ISO8859-2
``wx.FONTENCODING_CP1251`` Microsoft analogue of ISO8859-5
``wx.FONTENCODING_CP1252`` Microsoft analogue of ISO8859-1
======================================== =========================================================
As you may see, Microsoft's encoding partly mirror the standard ISO8859 ones, but there are (minor) differences even between
ISO8859-1 (Latin1, ISO encoding for Western Europe) and CP1251 (WinLatin1, standard code page for English versions of Windows)
and there are more of them for other encodings.
As you may see, Microsoft's encoding partly mirror the standard
ISO8859 ones, but there are (minor) differences even between ISO8859-1
(Latin1, ISO encoding for Western Europe) and CP1251 (WinLatin1,
standard code page for English versions of Windows) and there are more
of them for other encodings.
The situation is particularly complicated with Cyrillic encodings for which (more than) three incompatible encodings exist:
KOI8 (the old standard, widely used on the Internet), ISO8859-5 (ISO standard for Cyrillic) and CP1251 (WinCyrillic).
The situation is particularly complicated with Cyrillic encodings for
which (more than) three incompatible encodings exist: KOI8 (the old
standard, widely used on the Internet), ISO8859-5 (ISO standard for
Cyrillic) and CP1251 (WinCyrillic).
This abundance of (incompatible) encodings should make it clear that using encodings is less easy than it might seem.
The problems arise both from the fact that the standard encodings for the given language (say Russian, which is written
in Cyrillic) are different on different platforms and because the fonts in the given encoding might just not be installed
(this is especially a problem with Unix, or, in general, non-Win32 systems).
This abundance of (incompatible) encodings should make it clear that
using encodings is less easy than it might seem. The problems arise
both from the fact that the standard encodings for the given language
(say Russian, which is written in Cyrillic) are different on different
platforms and because the fonts in the given encoding might just not
be installed (this is especially a problem with Unix, or, in general,
non-Win32 systems).
To clarify, the :ref:`FontEnumerator` class may be used to enumerate both all available encodings and to find the facename(s)
in which the given encoding exists. If you can find the font in the correct encoding with :ref:`FontEnumerator` then your
troubles are over, but, unfortunately, sometimes this is not enough. For example, there is no standard way (that I know of,
please tell me if you do!) to find a font on a Windows system for KOI8 encoding (only for WinCyrillic one which is quite different),
so :ref:`FontEnumerator` will never return one, even if the user has installed a KOI8 font on his system.
To clarify, the :ref:`wx.FontEnumerator` class may be used to enumerate
both all available encodings and to find the facename(s) in which the
given encoding exists. If you can find the font in the correct
encoding with :ref:`wx.FontEnumerator` then your troubles are over, but,
unfortunately, sometimes this is not enough. For example, there is no
standard way (that I know of, please tell me if you do!) to find a
font on a Windows system for KOI8 encoding (only for WinCyrillic one
which is quite different), so :ref:`wx.FontEnumerator` will never return
one, even if the user has installed a KOI8 font on his system.
To solve this problem, a :ref:`FontMapper` class is provided.
To solve this problem, a :ref:`wx.FontMapper` class is provided.
This class stores the mapping between the encodings and the font face names which support them in :ref:`ConfigBase` object.
Of course, it would be fairly useless if it tried to determine these mappings by itself, so, instead, it (optionally) asks
the user and remembers his answers so that the next time the program will automatically choose the correct font.
This class stores the mapping between the encodings and the font face
names which support them in :ref:`wx.ConfigBase` object. Of course, it
would be fairly useless if it tried to determine these mappings by
itself, so, instead, it (optionally) asks the user and remembers his
answers so that the next time the program will automatically choose
the correct font.

68
docs/sphinx/rest_substitutions/overviews/font_overview.rst
View File

@@ -11,45 +11,63 @@
Introduction
------------
A font is an object which determines the appearance of text, primarily when drawing text to a window
or device context. A font is determined by the following parameters (not all of them have to be specified, of course):
A font is an object which determines the appearance of text, primarily
when drawing text to a window or device context. A font is determined
by the following parameters (not all of them have to be specified, of
course):
======================== ==========================================
**Point size** This is the standard way of referring to text size.
**Family** Supported families are: ``DEFAULT``, ``DECORATIVE``, ``ROMAN``, ``SCRIPT``, ``SWISS``, ``MODERN``. ``MODERN`` is a fixed pitch font; the others are either fixed or variable pitch.
**Style** The value can be ``NORMAL``, ``SLANT`` or ``ITALIC``.
**Weight** The value can be ``NORMAL``, ``LIGHT`` or ``BOLD``.
**Family** Supported families are: ``wx.DEFAULT``, ``wx.DECORATIVE``, ``wx.ROMAN``, ``wx.SCRIPT``, ``wx.SWISS``, ``wx.MODERN``. ``wx.MODERN`` is a fixed pitch font; the others are either fixed or variable pitch.
**Style** The value can be ``wx.NORMAL``, ``wx.SLANT`` or ``wx.ITALIC``.
**Weight** The value can be ``wx.NORMAL``, ``wx.LIGHT`` or ``wx.BOLD``.
**Underlining** The value can be ``True`` or ``False``.
**Face name** An optional string specifying the actual typeface to be used. If ``None``, a default typeface will chosen based on the family.
**Encoding** The font encoding (see ``FONTENCODING_XXX`` constants and the :ref:`Font Encodings <font encodings>` for more details)
**Encoding** The font encoding (see ``wx.FONTENCODING_XXX`` constants and the :ref:`Font Encodings <font encodings>` for more details)
======================== ==========================================
Specifying a family, rather than a specific typeface name, ensures a degree of portability across platforms because a
suitable font will be chosen for the given font family, however it doesn't allow to choose a font precisely as the parameters
above don't suffice, in general, to identify all the available fonts and this is where using the native font descriptions
may be helpful - see below.
Specifying a family, rather than a specific typeface name, ensures a
degree of portability across platforms because a suitable font will be
chosen for the given font family, however it doesn't allow to choose a
font precisely as the parameters above don't suffice, in general, to
identify all the available fonts and this is where using the native
font descriptions may be helpful - see below.
Under Windows, the face name can be one of the installed fonts on the user's system. Since the choice of fonts differs
from system to system, either choose standard Windows fonts, or if allowing the user to specify a face name, store the
family name with any file that might be transported to a different Windows machine or other platform.
Under Windows, the face name can be one of the installed fonts on the
user's system. Since the choice of fonts differs from system to
system, either choose standard Windows fonts, or if allowing the user
to specify a face name, store the family name with any file that might
be transported to a different Windows machine or other platform.
.. note:: There is currently a difference between the appearance of fonts on the two platforms, if the mapping mode is anything
other than ``MM_TEXT``. Under X, font size is always specified in points. Under MS Windows, the unit for text is points but
the text is scaled according to the current mapping mode. However, user scaling on a device context will also scale fonts under both environments.
.. note:: There is currently a difference between the appearance of
fonts on the two platforms, if the mapping mode is anything
other than ``MM_TEXT``. Under X, font size is always specified in
points. Under MS Windows, the unit for text is points but
the text is scaled according to the current mapping mode. However,
user scaling on a device context will also scale fonts under both
environments.
Native font information
-----------------------
An alternative way of choosing fonts is to use the native font description. This is the only acceptable solution if the user
is allowed to choose the font using the :ref:`FontDialog` because the selected font cannot be described using only the family
name and so, if only family name is stored permanently, the user would almost surely see a different font in the program later.
An alternative way of choosing fonts is to use the native font
description. This is the only acceptable solution if the user is
allowed to choose the font using the :ref:`wx.FontDialog` because the
selected font cannot be described using only the family name and so,
if only family name is stored permanently, the user would almost
surely see a different font in the program later.
Instead, you should store the value returned by :meth:`Font.GetNativeFontInfoDesc` and pass it to :meth:`Font.SetNativeFontInfo`
later to recreate exactly the same font.
Instead, you should store the value returned by
:meth:`wx.Font.GetNativeFontInfoDesc` and pass it to
:meth:`wx.Font.SetNativeFontInfo` later to recreate exactly the same
font.
.. note:: Note that the contents of this string depends on the platform and shouldn't be used for any other purpose (in particular, it is not
meant to be shown to the user). Also please note that although the native font information is currently implemented for Windows and
Unix (GTK+ and Motif) ports only, all the methods are available for all the ports and should be used to make your program work correctly
when they are implemented later.
.. note:: Note that the contents of this string depends on the
platform and shouldn't be used for any other purpose (in
particular, it is not meant to be shown to the user). Also please
note that although the native font information is currently
implemented for Windows and Unix (GTK+ and Motif) ports only, all
the methods are available for all the ports and should be used to
make your program work correctly when they are implemented later.

287
docs/sphinx/rest_substitutions/overviews/grid_overview.rst
View File

@@ -1,138 +1,149 @@
.. include:: headings.inc
.. _grid overview:
=================================================
|phoenix_title| **Grid Overview**
=================================================
:class:`~grid.Grid` and its related classes are used for displaying and editing tabular data.
:class:`~grid.Grid` supports custom attributes for the table cells, allowing to completely
customize its appearance and uses a separate grid table (:class:`~grid.GridTableBase` -derived)
class for the data management meaning that it can be used to display arbitrary amounts of data.
.. _grid getting started:
Getting Started
---------------
For simple applications you need only refer to the :class:`~grid.Grid` class in your code.
This example shows how you might create a grid in a frame or dialog constructor and illustrates
some of the formatting functions::
import wx
import wx.grid
class GridFrame(wx.Frame):
def __init__(self, parent):
wx.Frame.__init__(self, parent)
# Create a wxGrid object
grid = wx.grid.Grid(self, -1)
# Then we call CreateGrid to set the dimensions of the grid
# (100 rows and 10 columns in this example)
grid.CreateGrid(100, 10)
# We can set the sizes of individual rows and columns
# in pixels
grid.SetRowSize(0, 60)
grid.SetColSize(0, 120)
# And set grid cell contents as strings
grid.SetCellValue(0, 0, 'wxGrid is good')
# We can specify that some cells are read.only
grid.SetCellValue(0, 3, 'This is read.only')
grid.SetReadOnly(0, 3)
# Colours can be specified for grid cell contents
grid.SetCellValue(3, 3, 'green on grey')
grid.SetCellTextColour(3, 3, wx.GREEN)
grid.SetCellBackgroundColour(3, 3, wx.LIGHT_GREY)
# We can specify the some cells will store numeric
# values rather than strings. Here we set grid column 5
# to hold floating point values displayed with width of 6
# and precision of 2
grid.SetColFormatFloat(5, 6, 2)
grid.SetCellValue(0, 6, '3.1415')
self.Show()
if __name__ == '__main__':
app = wx.App(0)
frame = GridFrame(None)
app.MainLoop()
Here is a list of classes related to :class:`~grid.Grid`:
- :class:`~grid.Grid`: The main grid control class itself.
- :class:`~grid.GridTableBase`: The base class for grid data provider.
- :class:`~grid.GridStringTable`: Simple :class:`~grid.GridTableBase` implementation
supporting only string data items and storing them all in memory (hence suitable
for not too large grids only).
- :class:`~grid.GridCellAttr`: A cell attribute, allowing to customize its appearance
as well as the renderer and editor used for displaying and editing it.
- :class:`~grid.GridCellAttrProvider`: The object responsible for storing and retrieving the cell attributes.
- :class:`~grid.GridColLabelWindow`: The window showing the grid columns labels.
- :class:`~grid.GridRowLabelWindow`: The window showing the grid rows labels.
- :class:`~grid.GridCornerLabelWindow`: The window used in the upper left grid corner.
- :class:`~grid.GridWindow`: The window representing the main part of the grid.
- :class:`~grid.GridCellRenderer`: Base class for objects used to display a cell value.
- :class:`~grid.GridCellStringRenderer`: Renderer showing the cell as a text string.
- :class:`~grid.GridCellNumberRenderer`: Renderer showing the cell as an integer number.
- :class:`~grid.GridCellFloatRenderer`: Renderer showing the cell as a floating point number.
- :class:`~grid.GridCellBoolRenderer`: Renderer showing the cell as checked or unchecked box.
- :class:`~grid.GridCellEditor`: Base class for objects used to edit the cell value.
- :class:`~grid.GridCellStringEditor`: Editor for cells containing text strings.
- :class:`~grid.GridCellNumberEditor`: Editor for cells containing integer numbers.
- :class:`~grid.GridCellFloatEditor`: Editor for cells containing floating point numbers.
- :class:`~grid.GridCellBoolEditor`: Editor for boolean-valued cells.
- :class:`~grid.GridCellChoiceEditor`: Editor allowing to choose one of the predefined strings (and possibly enter new one).
- :class:`~grid.GridEvent`: The event sent by most of :class:`~grid.Grid` actions.
- :class:`~grid.GridSizeEvent`: The special event sent when a grid column or row is resized.
- :class:`~grid.GridRangeSelectEvent`: The special event sent when a range of cells is selected in the grid.
- :class:`~grid.GridEditorCreatedEvent`: The special event sent when a cell editor is created.
- :class:`~grid.GridSelection`: The object efficiently representing the grid selection.
- :class:`~grid.GridTypeRegistry`: Contains information about the data types supported by the grid.
.. _grid column and row sizes:
Column and Row Sizes
--------------------
.. note::
This section will discuss the resizing of :class:`~grid.Grid` rows only to avoid repetitions
but everything in it also applies to grid columns, just replace Row in the method names with Col.
Initially all :class:`~grid.Grid` rows have the same height, which can be modified for all of them
at once using :meth:`~grid.Grid.SetDefaultRowSize`. However, unlike simpler controls such as :class:`ListBox`
or :class:`ListCtrl`, :class:`~grid.Grid` also allows its rows to be individually resized to have their
own height using :meth:`~grid.Grid.SetRowSize` (as a special case, a row may be hidden entirely by
setting its size to 0, which is done by a helper :meth:`~grid.Grid.HideRow` method). It is also
possible to resize a row to fit its contents with :meth:`~grid.Grid.AutoSizeRow` or do it for all
rows at once with :meth:`~grid.Grid.AutoSizeRows`.
Additionally, by default the user can also drag the row separator lines to resize the rows interactively.
This can be forbidden completely by calling :meth:`~grid.Grid.DisableDragRowSize` or just for the
individual rows using :meth:`~grid.Grid.DisableRowResize`.
If you do allow the user to resize the grid rows, it may be a good idea to save their heights and
restore it when the grid is recreated the next time (possibly during a next program execution):
the functions :meth:`~grid.Grid.GetRowSizes` and :meth:`~grid.Grid.SetRowSizes` can help with this,
you will just need to serialize :class:`~grid.GridSizesInfo` structure returned by the former in
some way and deserialize it back before calling the latter.
.. include:: headings.inc
.. _grid overview:
=================================================
|phoenix_title| **Grid Overview**
=================================================
:class:`~wx.grid.Grid` and its related classes are used for displaying
and editing tabular data.
:class:`~wx.grid.Grid` supports custom attributes for the table cells,
allowing to completely customize its appearance and uses a separate
grid table (:class:`~wx.grid.GridTableBase` -derived) class for the
data management meaning that it can be used to display arbitrary
amounts of data.
.. _grid getting started:
Getting Started
---------------
For simple applications you need only refer to the
:class:`~wx.grid.Grid` class in your code. This example shows how you
might create a grid in a frame or dialog constructor and illustrates
some of the formatting functions::
import wx
import wx.grid
class GridFrame(wx.Frame):
def __init__(self, parent):
wx.Frame.__init__(self, parent)
# Create a wxGrid object
grid = wx.grid.Grid(self, -1)
# Then we call CreateGrid to set the dimensions of the grid
# (100 rows and 10 columns in this example)
grid.CreateGrid(100, 10)
# We can set the sizes of individual rows and columns
# in pixels
grid.SetRowSize(0, 60)
grid.SetColSize(0, 120)
# And set grid cell contents as strings
grid.SetCellValue(0, 0, 'wxGrid is good')
# We can specify that some cells are read.only
grid.SetCellValue(0, 3, 'This is read.only')
grid.SetReadOnly(0, 3)
# Colours can be specified for grid cell contents
grid.SetCellValue(3, 3, 'green on grey')
grid.SetCellTextColour(3, 3, wx.GREEN)
grid.SetCellBackgroundColour(3, 3, wx.LIGHT_GREY)
# We can specify the some cells will store numeric
# values rather than strings. Here we set grid column 5
# to hold floating point values displayed with width of 6
# and precision of 2
grid.SetColFormatFloat(5, 6, 2)
grid.SetCellValue(0, 6, '3.1415')
self.Show()
if __name__ == '__main__':
app = wx.App(0)
frame = GridFrame(None)
app.MainLoop()
Here is a list of classes related to :class:`~wx.grid.Grid`:
- :class:`~wx.grid.Grid`: The main grid control class itself.
- :class:`~wx.grid.GridTableBase`: The base class for grid data provider.
- :class:`~wx.grid.GridStringTable`: Simple :class:`~wx.grid.GridTableBase` implementation
supporting only string data items and storing them all in memory (hence suitable
for not too large grids only).
- :class:`~wx.grid.GridCellAttr`: A cell attribute, allowing to customize its appearance
as well as the renderer and editor used for displaying and editing it.
- :class:`~wx.grid.GridCellAttrProvider`: The object responsible for storing and retrieving the cell attributes.
- :class:`~wx.grid.GridColLabelWindow`: The window showing the grid columns labels.
- :class:`~wx.grid.GridRowLabelWindow`: The window showing the grid rows labels.
- :class:`~wx.grid.GridCornerLabelWindow`: The window used in the upper left grid corner.
- :class:`~wx.grid.GridWindow`: The window representing the main part of the grid.
- :class:`~wx.grid.GridCellRenderer`: Base class for objects used to display a cell value.
- :class:`~wx.grid.GridCellStringRenderer`: Renderer showing the cell as a text string.
- :class:`~wx.grid.GridCellNumberRenderer`: Renderer showing the cell as an integer number.
- :class:`~wx.grid.GridCellFloatRenderer`: Renderer showing the cell as a floating point number.
- :class:`~wx.grid.GridCellBoolRenderer`: Renderer showing the cell as checked or unchecked box.
- :class:`~wx.grid.GridCellEditor`: Base class for objects used to edit the cell value.
- :class:`~wx.grid.GridCellStringEditor`: Editor for cells containing text strings.
- :class:`~wx.grid.GridCellNumberEditor`: Editor for cells containing integer numbers.
- :class:`~wx.grid.GridCellFloatEditor`: Editor for cells containing floating point numbers.
- :class:`~wx.grid.GridCellBoolEditor`: Editor for boolean-valued cells.
- :class:`~wx.grid.GridCellChoiceEditor`: Editor allowing to choose one of the predefined strings (and possibly enter new one).
- :class:`~wx.grid.GridEvent`: The event sent by most of :class:`~wx.grid.Grid` actions.
- :class:`~wx.grid.GridSizeEvent`: The special event sent when a grid column or row is resized.
- :class:`~wx.grid.GridRangeSelectEvent`: The special event sent when a range of cells is selected in the grid.
- :class:`~wx.grid.GridEditorCreatedEvent`: The special event sent when a cell editor is created.
- :class:`~wx.grid.GridSelection`: The object efficiently representing the grid selection.
- :class:`~wx.grid.GridTypeRegistry`: Contains information about the data types supported by the grid.
.. _grid column and row sizes:
Column and Row Sizes
--------------------
.. note::
This section will discuss the resizing of :class:`~wx.grid.Grid` rows
only to avoid repetitions but everything in it also applies to grid
columns, just replace Row in the method names with Col.
Initially all :class:`~wx.grid.Grid` rows have the same height, which
can be modified for all of them at once using
:meth:`~wx.grid.Grid.SetDefaultRowSize`. However, unlike simpler
controls such as :class:`wx.ListBox` or :class:`wx.ListCtrl`,
:class:`~wx.grid.Grid` also allows its rows to be individually resized
to have their own height using :meth:`~wx.grid.Grid.SetRowSize` (as a
special case, a row may be hidden entirely by setting its size to 0,
which is done by a helper :meth:`~wx.grid.Grid.HideRow` method). It is
also possible to resize a row to fit its contents with
:meth:`~wx.grid.Grid.AutoSizeRow` or do it for all rows at once with
:meth:`~wx.grid.Grid.AutoSizeRows`.
Additionally, by default the user can also drag the row separator
lines to resize the rows interactively. This can be forbidden
completely by calling :meth:`~wx.grid.Grid.DisableDragRowSize` or just
for the individual rows using :meth:`~wx.grid.Grid.DisableRowResize`.
If you do allow the user to resize the grid rows, it may be a good
idea to save their heights and restore it when the grid is recreated
the next time (possibly during a next program execution): the
functions :meth:`~wx.grid.Grid.GetRowSizes` and
:meth:`~wx.grid.Grid.SetRowSizes` can help with this, you will just
need to serialize :class:`~wx.grid.GridSizesInfo` structure returned
by the former in some way and deserialize it back before calling the
latter.

170
docs/sphinx/rest_substitutions/overviews/html_overview.rst
View File

@@ -8,21 +8,23 @@
==================================
The :mod:`html` library provides classes for parsing and displaying HTML.
The :mod:`wx.html` library provides classes for parsing and displaying HTML.
It is not intended to be a high-end HTML browser. If you are looking for
something like that try http://www.mozilla.org/.
It is not intended to be a high-end HTML browser. If you are looking
for something like that try http://www.mozilla.org/.
:mod:`html` can be used as a generic rich text viewer - for example to display a
nice About Box (like those of GNOME apps) or to display the result of
database searching. There is a :class:`FileSystem` class which allows you to use
your own virtual file systems.
:mod:`wxhtml` can be used as a generic rich text viewer - for example
to display a nice About Box (like those of GNOME apps) or to display
the result of database searching. There is a :class:`wx.FileSystem`
class which allows you to use your own virtual file systems.
:class:`~html.HtmlWindow` supports tag handlers. This means that you can easily extend
:mod:`html` library with new, unsupported tags. Not only that, you can even use
your own application-specific tags!
:class:`~wx.html.HtmlWindow` supports tag handlers. This means that
you can easily extend :mod:`html` library with new, unsupported
tags. Not only that, you can even use your own application-specific
tags!
There is a generic :class:`~html.HtmlParser` class, independent of :class:`~html.HtmlWindow`.
There is a generic :class:`~wx.html.HtmlParser` class, independent of
:class:`~wx.html.HtmlWindow`.
.. _html quick start:
@@ -34,12 +36,13 @@ HTML quick start
Displaying HTML
~~~~~~~~~~~~~~~~
Class :class:`~html.HtmlWindow` (derived from :class:`ScrolledWindow`) is used to display
HTML documents.
Class :class:`~wx.html.HtmlWindow` (derived from
:class:`wx.ScrolledWindow`) is used to display HTML documents.
It has two important methods: :meth:`~html.HtmlWindow.LoadPage` and
:meth:`~html.HtmlWindow.SetPage`. LoadPage loads and displays HTML file while SetPage
displays directly the passed **string**. See the example::
It has two important methods: :meth:`~wx.html.HtmlWindow.LoadPage` and
:meth:`~wxhtml.HtmlWindow.SetPage`. LoadPage loads and displays HTML
file while SetPage displays directly the passed **string**. See the
example::
mywin.LoadPage("test.htm")
mywin.SetPage("htmlbody" \
@@ -52,62 +55,67 @@ displays directly the passed **string**. See the example::
Setting up HtmlWindow
~~~~~~~~~~~~~~~~~~~~~~
Because :class:`~html.HtmlWindow` is derived from :class:`ScrolledWindow` and not from
:class:`Frame`, it doesn't have visible frame. But the user usually wants to see
the title of HTML page displayed somewhere and the frame's titlebar is the
ideal place for it.
Because :class:`~wx.html.HtmlWindow` is derived from
:class:`wx.ScrolledWindow` and not from :class:`wx.Frame`, it doesn't
have visible frame. But the user usually wants to see the title of
HTML page displayed somewhere and the frame's titlebar is the ideal
place for it.
:class:`~html.HtmlWindow` provides 2 methods in order to handle this:
:meth:`~html.HtmlWindow.SetRelatedFrame` and :meth:`~html.HtmlWindow.SetRelatedStatusBar`.
See the example::
:class:`~wx.html.HtmlWindow` provides 2 methods in order to handle
this: :meth:`~wx.html.HtmlWindow.SetRelatedFrame` and
:meth:`~wx.html.HtmlWindow.SetRelatedStatusBar`. See the example::
html = wx.html.HtmlWindow(self)
html.SetRelatedFrame(self, "HTML : %%s")
html.SetRelatedStatusBar(0)
The first command associates the HTML object with its parent frame (this
points to :class:`Frame` object there) and sets the format of the title. Page
title "Hello, world!" will be displayed as "HTML : Hello, world!" in this
example.
The first command associates the HTML object with its parent frame
(this points to :class:`wx.Frame` object there) and sets the format of
the title. Page title "Hello, world!" will be displayed as "HTML :
Hello, world!" in this example.
The second command sets which frame's status bar should be used to display
browser's messages (such as "Loading..." or "Done" or hypertext links).
The second command sets which frame's status bar should be used to
display browser's messages (such as "Loading..." or "Done" or
hypertext links).
Customizing HtmlWindow
~~~~~~~~~~~~~~~~~~~~~~~
You can customize :class:`~html.HtmlWindow` by setting font size, font face and borders
(space between border of window and displayed HTML). Related functions:
You can customize :class:`~wx.html.HtmlWindow` by setting font size,
font face and borders (space between border of window and displayed
HTML). Related functions:
- :meth:`~html.HtmlWindow.SetFonts`
- :meth:`~html.HtmlWindow.SetBorders`
- :meth:`~html.HtmlWindow.ReadCustomization`
- :meth:`~html.HtmlWindow.WriteCustomization`
- :meth:`~wx.html.HtmlWindow.SetFonts`
- :meth:`~wx.html.HtmlWindow.SetBorders`
- :meth:`~wx.html.HtmlWindow.ReadCustomization`
- :meth:`~wx,html.HtmlWindow.WriteCustomization`
The last two functions are used to store user customization info :class:`ConfigBase`
stuff (for example in the registry under Windows, or in a dotfile under
Unix).
The last two functions are used to store user customization info
:class:`wx.ConfigBase` stuff (for example in the registry under
Windows, or in a dotfile under Unix).
HTML Printing
--------------
The :mod:`html` library provides printing facilities with several levels of
complexity. The easiest way to print an HTML document is to use the
:class:`~html.HtmlEasyPrinting` class.
The :mod:`wx.html` library provides printing facilities with several
levels of complexity. The easiest way to print an HTML document is to
use the :class:`~wx.html.HtmlEasyPrinting` class.
It lets you print HTML documents with only one command and you don't have to
worry about deriving from the :class:`Printout` class at all. It is only a simple
wrapper around the :class:`~html.HtmlPrintout`, normal wxPython printout class.
It lets you print HTML documents with only one command and you don't
have to worry about deriving from the :class:`wx.Printout` class at
all. It is only a simple wrapper around the
:class:`~wx.html.HtmlPrintout`, normal wxPython printout class.
And finally there is the low level class :class:`~html.HtmlDCRenderer` which you can
use to render HTML into a rectangular area on any DC.
And finally there is the low level class
:class:`~wx.html.HtmlDCRenderer` which you can use to render HTML into
a rectangular area on any DC.
It supports rendering into multiple rectangles with the same width. (The most
common use of this is placing one rectangle on each page or printing into two
columns.)
It supports rendering into multiple rectangles with the same
width. (The most common use of this is placing one rectangle on each
page or printing into two columns.)
.. _help files format:
@@ -115,12 +123,12 @@ columns.)
Help Files Format
------------------
:mod:`html` library can be used to show an help manual to the user; in fact, it
supports natively (through :class:`~html.HtmlHelpController`) a reduced version of MS
HTML Workshop format.
:mod:`wx.html` library can be used to show an help manual to the user; in
fact, it supports natively (through :class:`~wx.html.HtmlHelpController`)
a reduced version of MS HTML Workshop format.
A **book** consists of three files: the header file, the contents file and
the index file.
A **book** consists of three files: the header file, the contents file
and the index file.
You can make a regular zip archive of these files, plus the HTML and any
image files, for HTML (or helpview) to read; and the ``".zip"`` file can
@@ -136,8 +144,8 @@ Header file (.hhp)
.. highlight:: rst
The header file must contain these lines (and may contain additional lines
which are ignored)::
The header file must contain these lines (and may contain additional
lines which are ignored)::
Contents file=filename.hhc
Index file=filename.hhk
@@ -186,7 +194,7 @@ contains exactly one list (``<ul>`` ... ``</ul>`` statement)::
You can modify value attributes of param tags. The *topic name* is name of
chapter/topic as is displayed in contents, *filename.htm* is the HTML page
name (relative to the ``".hhp"`` file) and *numeric_id* is optional - it is
used only when you use :meth:`~html.HtmlHelpController.Display`.
used only when you use :meth:`~wx.html.HtmlHelpController.Display`.
Items in the list may be nested - one ``<li>`` statement may contain a
``<ul>`` sub-statement::
@@ -228,11 +236,11 @@ ignored and sublists are **not** allowed.
Input Filters
--------------
The :mod:`html` library provides a mechanism for reading and displaying files of
The :mod:`wx.html` library provides a mechanism for reading and displaying files of
many different file formats.
:meth:`~html.HtmlWindow.LoadPage` can load not only HTML files but any known file. To
make a file type known to :class:`~html.HtmlWindow` you must create a :class:`~html.HtmlFilter`
:meth:`~wx.html.HtmlWindow.LoadPage` can load not only HTML files but any known file. To
make a file type known to :class:`~wxzhtml.HtmlWindow` you must create a :class:`~wx.html.HtmlFilter`
filter and register it using :meth:`~html.HtmlWindow.AddFilter`.
@@ -241,8 +249,8 @@ filter and register it using :meth:`~html.HtmlWindow.AddFilter`.
Cells and Containers
---------------------
This article describes mechanism used by :class:`~html.HtmlWinParser` and
:class:`~html.HtmlWindow` to parse and display HTML documents.
This article describes mechanism used by :class:`~wx.html.HtmlWinParser` and
:class:`~wx.html.HtmlWindow` to parse and display HTML documents.
Cells
@@ -252,7 +260,7 @@ You can divide any text (or HTML) into small fragments. Let's call these
fragments **cells**. Cell is for example one word, horizontal line, image or
any other part of document. Each cell has width and height (except special
"magic" cells with zero dimensions - e.g. colour changers or font changers).
See :class:`~html.HtmlCell`.
See :class:`~wx.html.HtmlCell`.
Containers
@@ -260,7 +268,7 @@ Containers
Container is kind of cell that may contain sub-cells. Its size depends on
number and sizes of its sub-cells (and also depends on width of window). See
:class:`~html.HtmlContainerCell`, :meth:`~html.HtmlCell.Layout`. This image shows the cells and
:class:`~wx.html.HtmlContainerCell`, :meth:`~wx.html.HtmlCell.Layout`. This image shows the cells and
containers:
.. image:: _static/images/overviews/overview_html_contbox.png
@@ -272,15 +280,15 @@ containers:
Using Containers in Tag Handler
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:class:`~html.HtmlWinParser` provides a user-friendly way of managing containers. It is
:class:`~wx.html.HtmlWinParser` provides a user-friendly way of managing containers. It is
based on the idea of opening and closing containers.
Use :meth:`~html.HtmlWinParser.OpenContainer` to open new a container *within* an
Use :meth:`~wx.html.HtmlWinParser.OpenContainer` to open new a container *within* an
already opened container. This new container is a *sub-container* of the old
one. (If you want to create a new container with the same depth level you can
call ``CloseContainer()``; ``OpenContainer()``; ).
Use :meth:`~html.HtmlWinParser.CloseContainer` to close the container. This doesn't
Use :meth:`~wx.html.HtmlWinParser.CloseContainer` to close the container. This doesn't
create a new container with same depth level but it returns "control" to the
parent container. See explanation:
@@ -323,13 +331,13 @@ new container.
The result was that we had *same* depth level after executing. This is
general rule that should be followed by tag handlers: leave depth level of
containers unmodified (in other words, number of OpenContainer and
CloseContainer calls should be same within :meth:`~html.HtmlTagHandler.HandleTag` 's
CloseContainer calls should be same within :meth:`~wx.html.HtmlTagHandler.HandleTag` 's
body).
.. note::
Notice that it would be usually better to use
:meth:`~html.HtmlContainerCell.InsertCell` instead of adding text to the parser
:meth:`~wx.html.HtmlContainerCell.InsertCell` instead of adding text to the parser
directly.
@@ -338,12 +346,12 @@ body).
Tag Handlers
-------------
The :mod:`html` library provides architecture of pluggable *tag* handlers. Tag
The :mod:`wx.html` library provides architecture of pluggable *tag* handlers. Tag
handler is class that understands particular HTML tag (or tags) and is able
to interpret it.
:class:`~html.HtmlWinParser` has a static table of **modules**. Each module contains
one or more tag handlers. Each time a new :class:`~html.HtmlWinParser` object is
:class:`~wx.html.HtmlWinParser` has a static table of **modules**. Each module contains
one or more tag handlers. Each time a new :class:`~wx.html.HtmlWinParser` object is
constructed all modules are scanned and handlers are added to HtmlParser's
list of available handlers.
@@ -351,7 +359,7 @@ list of available handlers.
How it works
~~~~~~~~~~~~~
Common tag handler's :meth:`~html.HtmlTagHandler.HandleTag` method works in four
Common tag handler's :meth:`~wx.html.HtmlTagHandler.HandleTag` method works in four
steps:
- Save state of parent parser into local variables
@@ -359,21 +367,21 @@ steps:
- Parse text between the tag and paired ending tag (if present)
- Restore original parser state
See :class:`~html.HtmlWinParser` for methods for modifying parser's state. In general
See :class:`~wx.html.HtmlWinParser` for methods for modifying parser's state. In general
you can do things like opening/closing containers, changing colors, fonts etc...
Providing own tag handlers
~~~~~~~~~~~~~~~~~~~~~~~~~~~
See the :mod:`lib.wxpTag` on how to provide your own tag handlers.
See the :mod:`wx.lib.wxpTag` on how to provide your own tag handlers.
Tag handlers
~~~~~~~~~~~~~
The handler is derived from :class:`~html.HtmlWinTagHandler` (or directly from
:class:`~html.HtmlTagHandler`).
The handler is derived from :class:`~wx.html.HtmlWinTagHandler` (or directly from
:class:`~wx.html.HtmlTagHandler`).
.. _tags supported by wxhtml:
@@ -381,17 +389,17 @@ The handler is derived from :class:`~html.HtmlWinTagHandler` (or directly from
Tags supported by :mod:`html`
-----------------------------
:mod:`html` is not a full implementation of HTML standard. Instead, it supports most
:mod:`wx.html` is not a full implementation of HTML standard. Instead, it supports most
common tags so that it is possible to display *simple* HTML documents with
it. (For example it works fine with pages created in Netscape Composer or
generated by tex2rtf).
Following tables list all tags known to :mod:`html`, together with supported
Following tables list all tags known to :mod:`wx.html`, together with supported
parameters.
A tag has general form of ``tagname`` param_1 param_2 ... param_n where
param_i is either ``paramname="paramvalue"`` or ``paramname=paramvalue`` -
these two are equivalent. Unless stated otherwise, :mod:`html` is case-
these two are equivalent. Unless stated otherwise, :mod:`wx.html` is case-
insensitive.
@@ -646,7 +654,7 @@ List of supported tags
List of supported styles
~~~~~~~~~~~~~~~~~~~~~~~~~
:mod:`html` doesn't really have CSS support but it does support a few simple
:mod:`wx.html` doesn't really have CSS support but it does support a few simple
styles: you can use ``"text-align"``, ``"width"``, ``"vertical-align"`` and
``"background"`` with all elements and for ``SPAN`` elements a few other
styles are additionally recognized: