• R/O
  • SSH

tkpane: Commit

Default repository for tkpane.py.


Commit MetaInfo

Revisão9f78f82c1a16a0fd1cad49f9fe870c5dbba75058 (tree)
Hora2018-03-18 02:19:09
AutorDreas Nielsen <dreas.nielsen@gmai...>
CommiterDreas Nielsen

Mensagem de Log

Revised documentation and updated version to 1.0.0.

Mudança Sumário

Diff

diff -r f082099bdfa7 -r 9f78f82c1a16 CHANGELOG.rst
--- a/CHANGELOG.rst Wed Mar 14 21:16:06 2018 -0700
+++ b/CHANGELOG.rst Sat Mar 17 10:19:09 2018 -0700
@@ -4,6 +4,7 @@
44 ========== ======= =================================================================================
55 Date Version Revision
66 ========== ======= =================================================================================
7+2018-03-17 1.0.0 Revised documentation.
78 2018-03-14 0.30.0 Modified EntryPane; added parameters 'required' and 'blank_is_valid'. Modified RadiobuttonPane to allow either orientation. Initialized datadict in panes with default values. Added function 'run_validity_callbacks()'.
89 2018-03-12 0.27.0 Modified title of UserPane in lib.py.
910 2018-03-10 0.26.0 Added 'set_entry_validator()' method to EntryPane in lib.py. Changed invalid colors to be configurable at module level. Changed use of ttk or tk widgets to be configurable at the module level.
diff -r f082099bdfa7 -r 9f78f82c1a16 doc/source/conf.py
--- a/doc/source/conf.py Wed Mar 14 21:16:06 2018 -0700
+++ b/doc/source/conf.py Sat Mar 17 10:19:09 2018 -0700
@@ -55,9 +55,9 @@
5555 # built documents.
5656 #
5757 # The short X.Y version.
58-version = u'0.30.0'
58+version = u'1.0.0'
5959 # The full version, including alpha/beta/rc tags.
60-release = u'0.30.0'
60+release = u'1.0.0'
6161
6262 # The language for content autogenerated by Sphinx. Refer to documentation
6363 # for a list of supported languages.
diff -r f082099bdfa7 -r 9f78f82c1a16 doc/source/figure_panes_borders.png
Binary file doc/source/figure_panes_borders.png has changed
diff -r f082099bdfa7 -r 9f78f82c1a16 doc/source/index.rst
--- a/doc/source/index.rst Wed Mar 14 21:16:06 2018 -0700
+++ b/doc/source/index.rst Sat Mar 17 10:19:09 2018 -0700
@@ -19,6 +19,27 @@
1919 other panes. Other application code can also easily obtain a pane's
2020 data in the form of a Python dictionary.
2121
22+The following figure illustrates a user interface containing four
23+separate panes. Borders have been added to the panes so that they are
24+easily distinguished for the purpose of this illustration. Both input
25+and output file names are required but currently invalid (missing), as
26+indicated by the light red background of the entry widgets. Entry of
27+output comments is dependent on the specification of an output file,
28+and so is currently disabled. The "OK" button is dependent on entry of
29+both an input and output file, and so is also currently disabled.
30+
31+.. figure:: figure_panes_borders.png
32+ :align: center
33+ :alt: Panes with borders
34+
35+ Figure 1. Four Panes with Borders Added
36+
37+Each of these dependencies is established by a single method call. The
38+same method calls ensure that, when the "OK" button is enabled, the
39+button pane's internal data will include the input and output filenames
40+and the comment; no other application-level code is required for the
41+button pane to reference any other panes to obtain their data.
42+
2243 .. toctree::
2344 :maxdepth: 3
2445 :caption: Contents:
@@ -145,32 +166,33 @@
145166 data dictionary using the ``all_data()`` method of the second pane.
146167
147168 Just as the *disable* action is the converse of the *enable* action,
148-its data sharing behavior is intended to facilitate data removal rather
149-than data sharing. When the *disable* action is performed on a pane
150-(its ``disable()`` method called), the caller passes a list of all of
151-its own data dictionary's keys. The recipient then can, if
152-appropriate, use this list of keys to strip the caller's data (if any)
153-out of its own data dictionary.
169+its data sharing behavior is intended to facilitate removal of data
170+from the target pane's data dictionary rather than addition of data.
171+When the *disable* action is performed on a pane (its ``disable()``
172+method called), the caller passes a list of all of its own data
173+dictionary's keys. The target pane then can, if appropriate, use this
174+list of keys to strip the caller's data (if any) out of its own data
175+dictionary.
154176
155-The data sharing interactions accompanying the *enable* and *disable*
156-actions can be illustrated with an example. Suppose that a pane
157-named ``button_pane`` is to be enabled only if two other panes, named
158-``entry_a`` and ``entry_b`` both have valid data. Initially
159-the ``button_pane`` would be disabled, and then a sequence like the
177+The data sharing interactions accompanying the *enable* and *disable*
178+actions can be illustrated with the following example. Suppose that a
179+pane named ``button_pane`` is to be enabled only if two other panes,
180+named ``entry_a`` and ``entry_b`` both have valid data. Initially the
181+``button_pane`` would be disabled, and then a sequence like the
160182 following might take place:
161183
162184 .. code-block:: none
163185
164186 User enters a valid value into entry_a.
165- entry_a calls the enable() method of button_pane, passing its own data.
187+ entry_a automatically calls the enable() method of button_pane, passing its own data.
166188 button_pane adds the data to its own dictionary.
167189 button_pane is still missing data from entry_b and so does not enable itself.
168190 User enters a valid value into entry_b.
169- entry_b calls the enable() method of button_pane, passing its own data.
191+ entry_b automatically calls the enable() method of button_pane, passing its own data.
170192 button_pane adds the data to its own dictionary.
171193 button_pane has data from both entry panes and so enables itself.
172194 User edits entry_a, making the data invalid.
173- entry_a calls the disable() method of button_pane, passing its dictionary keys.
195+ entry_a automatically calls the disable() method of button_pane, passing its dictionary keys.
174196 button_pane uses the keys to remove the corrresponding data from its own dictionary.
175197 button_pane is now missing data from entry_a and so disables itself.
176198
@@ -236,10 +258,10 @@
236258 * The pane's ``clear()`` method is called (list ``on_clear``).
237259 * The pane's ``disable()`` method is called (list ``on_disable``).
238260
239-All of the callback functions in each corresponding list are called whenever
240-one of these conditions occurs. For the *enable*, *clear*, and
241-*disable* actions the callback functions are called after the pane
242-itself is enabled, cleared, or disabled, respectively.
261+All of the callback functions in each list are called
262+whenever the corresponding condition occurs. For the *enable*,
263+*clear*, and *disable* actions the callback functions are called after
264+the pane itself is enabled, cleared, or disabled, respectively.
243265
244266 Some of these callback lists are automatically populated by the
245267 ``requires()`` and ``can_use()`` methods. All of the callback lists
@@ -248,19 +270,20 @@
248270
249271 As described in the previous section, the ``enable()`` and
250272 ``disable()`` methods take different arguments: the first takes a
251-dictionary, and the second takes a list. The ``clear()`` method takes
252-a list of dictionary keys just as does the ``disable()`` method. Any
253-callback list may contain a mixture of ``enable()`` and ``disable()``
254-methods, and consequently different items in a callback list may
255-require different arguments. The pane that calls those functions must
256-know what argument to provide to each. To provide that information,
257-the ``tkpane`` package provides several callback handler
258-(``CbHandler``) classes that are used to associate appropriate
259-information about argument types with each callback function. These
260-``CbHandler`` classes are documented below. The callback lists are
261-lists of ``CbHandler`` objects, not simply lists of functions. If the
262-callback lists must be directly addressed during UI construction, it is
263-essential that callback functions be wrapped in ``CbHandler`` objects.
273+dictionary, and the second takes a list of dictionary keys. The
274+``clear()`` method takes a list of dictionary keys just as does the
275+``disable()`` method. Any callback list may contain a mixture of
276+``enable()`` and ``disable()`` methods, and consequently different
277+items in a callback list may require different arguments. The pane
278+that calls those functions must know what argument to provide to each.
279+To provide that information, the ``tkpane`` package provides several
280+callback handler (``CbHandler``) classes that are used to associate
281+appropriate information about argument types with each callback
282+function. These ``CbHandler`` classes are documented below. The
283+callback lists are lists of ``CbHandler`` objects, not simply lists of
284+functions. If the callback lists must be directly addressed during UI
285+construction, it is essential that callback functions be wrapped in
286+``CbHandler`` objects.
264287
265288
266289
@@ -286,8 +309,9 @@
286309 enclosing frame widget to the pane class's constructor method.
287310 4. If needed, use the ``requires()`` method to identify which frames
288311 depend on valid data from other frames.
289-5. If needed, use the ``requires_datavalue()`` method to specify
290- individual data values that a pane must have before it can be enabled.
312+5. If needed, use the ``requires_datavalue()`` method to indicate that
313+ the pane must have a specific key and value in its data dictionary
314+ for it to enable itself.
291315 6. If needed, use the ``can_use()`` method to indicate that one pane
292316 will accept another pane's data, but does not require it.
293317 7. If needed, append any additional required callback handler objects
@@ -298,10 +322,10 @@
298322 ``TkPane`` subclass object.
299323 9. If needed, perform any additional pane-specific or application-specific
300324 configuration or initialization.
301-10. If needed, call the ``tkpane.enable_or_disable_all()`` method with
302- a list of panes as an argument; this ensures that the application
303- (or window) starts with each pane enabled or disabled as
304- appropriate.
325+10. If needed, initialize the appearance and data sharing of the UI by
326+ calling the ``tkpane.run_validity_callbacks()`` and
327+ ``tkpane.enable_or_disable_all()`` functions, passing each a list of
328+ panes as an argument.
305329
306330
307331
@@ -322,7 +346,7 @@
322346 panes. A custom subclass might use other internal data storage
323347 mechanisms (e.g., class attributes), and if so, those data values
324348 will not appear in this data dictionary. If no valid data values
325- have been entered into the pane, they (or their keys) will not
349+ have been entered into the pane, they (and their keys) will not
326350 be present in the data dictionary that is returned.
327351
328352 can_use(other_pane)
@@ -397,13 +421,15 @@
397421 provided by a multiple-select listbox), then the pane will be
398422 enabled if any of the items in that list match the specified data
399423 value (or any of the values in the list, if the specified data
400- value is a list). Commonly the key and and value used as arguments
424+ value is a list). Commonly the key and value used as arguments
401425 to this method will be obtained from another pane (e.g., via the
402426 ``enable()`` method), but this method does not refer explicitly to
403427 any other pane. Often when the ``requires_datavalue()`` method is
404428 used, it will be appropriate to also use the ``requires()`` method
405429 with an argument identifying the other pane that provides the data
406- key and value.
430+ key and value. This method is useful when one pane (e.g., one
431+ containing radio buttons) must enable different other panes
432+ depending on its own value.
407433
408434 set_data(data_dictionary)
409435 A generalized method intended to be used to send data or other
@@ -446,12 +472,12 @@
446472
447473 * Panes that handle user-entered data, where the data may be
448474 invalid (e.g., when required and missing). See
449- ``tkpane.lib.EntryPane`` and Example 2.
475+ ``tkpane.lib.EntryPane`` and :ref:`Example 2 <example2>`.
450476 * Panes that handle user-entered data where the data are
451477 constrained to never be invalid. See ``tkpane.lib.ScalePane``
452478 and ``tkpane.lib.UserPane``.
453479 * Panes that do not handle user-entered data. See
454- ```tkpane.lib.MessagePane`` and ``tkpane.lib.ButtonPane```.
480+ ``tkpane.lib.MessagePane`` and ``tkpane.lib.ButtonPane``.
455481
456482 Each custom pane must call the TkPane class's own initialization method,
457483 passing it the following values:
@@ -467,9 +493,9 @@
467493
468494 tkpane.TkPane.__init__(self, parent, pane_name, tkpane.lib.frame_config_opts(), tkpane.lib.frame_grid_opts())
469495
470-Each custom pane that manages data should also initialize the ``datakeylist``
471-attribute. This should be a list of the key names for the data values
472-that are managed by the pane.
496+Each custom pane that manages data should also initialize the
497+``datakeylist`` attribute. This should be a list of the dictionary key
498+names for the data values that are managed by the pane.
473499
474500 Each custom pane that manages data should also override the following
475501 six methods of the TkPane class:
@@ -482,7 +508,7 @@
482508 are valid. If no widget is specified, all entry widgets in the pane
483509 should be evaluated.
484510
485-save_data(is_valid, entry_widget)
511+save_data(is_valid, entry_widget=None)
486512 Modify the pane's data dictionary, either updating it from the widget
487513 if the widget's data are valid, or clearing the relevant data if the
488514 widget's data are not valid.
@@ -501,16 +527,16 @@
501527 Validating Data
502528 ==============================================================
503529
504-Each custom TkPane subclass that handles data must define a
505-data validation method named ``valid_data``. This method will be called
506-on every change to data in the pane's widget(s). For example, for
507-the ``EntryPane`` in ``tkpane.lib``, the validation method will be
508-called after every character is typed. This method must return
509-True or False to indicate whether or not the pane's data are valid.
510-A return value of False does not cause the change just made to be
511-rejected or rolled back, but the validation method of a pane may
512-directly manipulate the pane's widgets or Tkinter variables, or call
513-other pane methods such as ``set_data()`` to alter the data.
530+Each custom TkPane subclass that handles data must define a data
531+validation method named ``valid_data``. This method will be called on
532+every change to data in the pane's widget(s). For example, for the
533+``EntryPane`` class in ``tkpane.lib``, the validation method will be
534+called after every character is typed. This method must return True or
535+False to indicate whether or not the pane's data are valid. A return
536+value of False does not cause the change just made to be rejected or
537+rolled back, but the validation method of a pane may directly
538+manipulate the pane's widgets or Tkinter variables, or call other pane
539+methods such as ``set_data()`` to alter the data.
514540
515541 Pane classes defined in ``tkpane.lib`` generally consider a pane's data
516542 to be invalid if a data value is required but missing. Several of the
@@ -530,6 +556,7 @@
530556 * EntryPane: set_entry_validator()
531557 * InputFilePane: set_filename_validator()
532558 * InputFilePane2: set_filename_validator()
559+* TextPane: set_entry_validator()
533560 * UserPane: set_user_validator()
534561 * UserPasswordPane: set_user_validator()
535562
@@ -540,10 +567,11 @@
540567
541568 When a custom pane class's initialization method calls the ``TkPane``
542569 class's initialization method, it must provide dictionaries of frame
543-configuration and gridding option. The ``tkpane.lib`` package
570+configuration and gridding options The ``tkpane.lib`` package
544571 provides a number of pre-defined pane styles, and the ability to create
545572 new styles, to simplify this process and easily standardize pane
546-appearance.
573+appearance. The pane style definitions have no correspondence with
574+Style classes that can be used with ttk widgets.
547575
548576 This is carried out by instantiating a ``PaneStyle`` object, which
549577 is initialized with a style name, a dictionary of frame configuration
@@ -574,18 +602,19 @@
574602 The provided pane styles are:
575603
576604 default
577- Six pixels of padding in both the X and Y directions. In combination
578- with the three-pixel spacing around widgets, this results in widgets
579- on adjacent panes being separated by 18 pixels. As the name implies,
580- this is the default setting for ``tkpane.lib``.
605+ Six pixels of internal padding within the enclosing frame in both
606+ the X and Y directions. In combination with the three-pixel
607+ spacing around widgets, this results in widgets on adjacent panes
608+ being separated by 18 pixels. As the name implies, this is the
609+ default setting for ``tkpane.lib``.
581610
582611 plain
583- No padding in either the X or Y directions.
612+ No internal frame padding in either the X or Y directions.
584613
585614 closex
586- Six pixels of padding in the Y direction and no padding in the X
587- direction. This is appropriate for a series of horizontally-adjacent
588- ButtonPane panes.
615+ Six pixels of internal frame padding in the Y direction and no
616+ padding in the X direction. This is appropriate for a series of
617+ horizontally-adjacent ButtonPane panes.
589618
590619 closey
591620 Zero pixels of padding in the Y direction and six pixels of padding
@@ -616,15 +645,16 @@
616645 Highlighting Invalid Data
617646 ==============================================================
618647
619-By default, if a pane's is designated as required (e.g., by reference
620-to the pane in the ``requires()`` method of another pane), and the
621-pane's data are invalid, the widget's background is colored a light red.
648+By default, if a pane's data is designated as required (e.g., by
649+reference to the pane in the ``requires()`` method of another pane),
650+and the pane's data are invalid, the widget's background is colored a
651+light red, as shown in the following figure.
622652
623653 .. figure:: figure_invalid.png
624654 :align: center
625655 :alt: Invalid widget color
626656
627- Figure 1. Coloring of Widgets with Invalid Data
657+ Figure 2. Coloring of Widgets with Invalid Data
628658
629659 The default colors used to indicate that an entry is required but
630660 invalid are module-level variables:
@@ -651,11 +681,12 @@
651681
652682 The ``invalid_color`` setting also serves as a switch to disable changes
653683 to the background color of widgets with required but invalid data.
654-Setting the 'invalid' color to None will turn off the automatic changes
684+Setting ``invalid_color`` to None will turn off the automatic changes
655685 to widget background colors.
656686
657-Note that some widgets (including the checkbox and scale) do not
658-respond to any changes in background colors.
687+Note that some widgets (including the checkbox and scale) do not
688+respond to any changes in background colors. These two widgets,
689+however, should not have any invalid state.
659690
660691
661692
@@ -685,7 +716,7 @@
685716 :members:
686717
687718
688-Action Method Handling Classes
719+Action Method Handling Classes (CbHandler Classes)
689720 --------------------------------------------------------------
690721
691722 Every callback function used by a pane must be wrapped in one of the
@@ -739,11 +770,15 @@
739770 Examples
740771 ==============================================================
741772
742-Following are two examples. The first illustrates the creation
773+Following are three examples. The first illustrates the creation
743774 of a simple application using panes that are defined in ``tkpane.lib``,
744-and the second illustrates the construction of a simple custom pane.
775+the second illustrates the construction of a simple custom pane, and
776+the third is a small working application to display selected columns
777+from a CSV file.
745778
746779
780+.. _example1:
781+
747782 Example 1: Using Panes from ``tkpane.lib``
748783 --------------------------------------------------------------
749784
@@ -850,16 +885,17 @@
850885 root.mainloop()
851886
852887
853-This will produce an application that looks like Figure 2, below,
888+This will produce an application that looks like Figure 3, below,
854889 after an input file name has been entered.
855890
856891 .. figure:: figure_1.png
857892 :align: center
858893 :alt: Example Pane Usage
859894
860- Figure 2. Example Pane Usage
895+ Figure 3. Example Pane Usage
861896
862897
898+.. _example2:
863899
864900 Example 2. Construction of a Custom Pane
865901 --------------------------------------------------------------
@@ -1007,7 +1043,8 @@
10071043 procedures of the ``TkPane`` class will not operate properly.
10081044
10091045 The ``__init__`` method for this pane class does not set the pane's
1010-``required`` attribute. The constructors for other pane classes might.
1046+``required`` attribute. The constructors for other pane classes might
1047+(as illustrated in :ref:`Example 1 <example1>`).
10111048 The ``required`` attribute of objects of this class might be set after
10121049 instantiation, either directly by the user or by a ``requires()``
10131050 method call from another pane that uses an object of this pane class
@@ -1024,7 +1061,7 @@
10241061 that accepts the arguments provided by the ``trace()`` method and
10251062 simply chains to the ``TkPane`` class method ``handle_change_validity()``.
10261063 As the word "handle" in the name of this latter method implies,
1027-the method calls all the Handler callbacks to enable or disable other
1064+the method calls all the CbHandler callbacks to enable or disable other
10281065 panes as necessary.
10291066
10301067 Because this custom class handles data entry, it overrides the six
@@ -1060,6 +1097,8 @@
10601097 for all custom data-handling pane classes.
10611098
10621099
1100+.. _example3:
1101+
10631102 Example 3. A Simple CSV Explorer Application
10641103 --------------------------------------------------------------
10651104
@@ -1222,18 +1261,7 @@
12221261 Notes
12231262 ==============================================================
12241263
1225-1. By default, widgets on panes that have their ``required`` attribute
1226- set to True, and which do not contain valid data, have their
1227- background color set to light red. This color can be changed with
1228- the ``set_invalid_color()`` method of the ``TkPane`` class.
1229-
1230-.. note::
1231-
1232- The 'invalid' background color for themed (ttk) widgets is not
1233- set to light red on Windows when native widgets are being
1234- used (as in the default theme).
1235-
1236-2. Every pane that manages data must have a dictionary key (or keys)
1264+1. Every pane that manages data must have a dictionary key (or keys)
12371265 to identify the data value(s). Every pane class in ``tkpane.lib``
12381266 has a default name (or names) for these data key(s). When multiple
12391267 panes of the same class are on the same UI, their data key names
@@ -1247,12 +1275,12 @@
12471275 any dependencies are established with the ``requires()`` or
12481276 ``can_use()`` methods.
12491277
1250-3. The ``status_reporter`` attribute of a pane, if used, must be set
1278+2. The ``status_reporter`` attribute of a pane, if used, must be set
12511279 to an object (e.g., another pane) that has a ``set_status()`` method
12521280 and, if needed, a ``clear_status()`` method. The ``StatusProgressPane``
12531281 and ``TextPane`` classes in ``tkpane.lib`` have these methods.
12541282
1255-4. The ``progress_reporter`` attribute of a pane, if used, must be set
1283+3. The ``progress_reporter`` attribute of a pane, if used, must be set
12561284 to an object (e.g., another pane) that has the following methods:
12571285
12581286 * ``set_determinate()``: Sets the progress bar to alter the progress
@@ -1285,15 +1313,16 @@
12851313 =================================================
12861314
12871315 **TkLayout** (`code <https://pypi.org/project/tklayout/>`_ and `documentation <http://tklayout.readthedocs.io/en/latest/>`_)
1288- The TkLayout Python package simplifies the construction of a Tkinter
1289- interface by allowing the developer to describe the structure of the
1290- UI from the inside out, as successive nestings of rows and
1291- columns of elements, and then to create all of the Tkinter frames
1292- to implement this structure with one command. Although ``tklayout``
1293- and ``tkpane`` can be used entirely independently, they work together
1294- well because panes can easily be used to fill the UI elements defined
1295- in the layout. Examples 1 and 3 both show the use of ``tklayout``
1296- with ``tkpane``.
1316+ The TkLayout Python package simplifies the construction of a
1317+ Tkinter interface by allowing the developer to describe the
1318+ structure of the UI from the inside out, as successive nestings of
1319+ rows and columns of elements, and then to create all of the Tkinter
1320+ frames to implement this structure with one command. Although
1321+ ``tklayout`` and ``tkpane`` can be used entirely independently,
1322+ they work together well because panes can easily be used to fill
1323+ the UI elements defined in the layout. Examples :ref:`1
1324+ <example1>` and :ref:`3 <example3>` both show the use of
1325+ ``tklayout`` with ``tkpane``.
12971326
12981327
12991328 Copyright and License
@@ -1316,9 +1345,9 @@
13161345 ================================================================
13171346
13181347 Elizabeth Shea
1319- Conceptualization of pane interactions, radio button pane, original
1320- versions of ``UserPane`` and ``OutputDirPane``, and rigorous
1321- testing.
1348+ Assistance with the conceptualization of pane interactions, radio
1349+ button pane, original versions of ``UserPane`` and
1350+ ``OutputDirPane``, and rigorous testing.
13221351
13231352
13241353
diff -r f082099bdfa7 -r 9f78f82c1a16 setup.py
--- a/setup.py Wed Mar 14 21:16:06 2018 -0700
+++ b/setup.py Sat Mar 17 10:19:09 2018 -0700
@@ -2,7 +2,7 @@
22
33 setup(name='tkpane',
44 packages=['tkpane'],
5- version='0.30.0',
5+ version='1.0.0',
66 description="Encapsulates Tkinter UI elements in 'panes' that can be combined into an overall UI, integrating them by specifying callback functions and data keys.",
77 author='Dreas Nielsen',
88 author_email='dreas.nielsen@gmail.com',
diff -r f082099bdfa7 -r 9f78f82c1a16 test/test_2.py
--- a/test/test_2.py Wed Mar 14 21:16:06 2018 -0700
+++ b/test/test_2.py Sat Mar 17 10:19:09 2018 -0700
@@ -40,7 +40,7 @@
4040 # layout are all named, and each of these named elements will correspond to
4141 # a pane.
4242 lo = tklayout.AppLayout()
43-app = lo.column_elements(["infile_pane", "outfile_pane", "entry_pane", "text_pane", "button_pane"], row_weights=[0,0,1,0,0])
43+app = lo.column_elements(["infile_pane", "outfile_pane", "entry_pane", "text_pane", "button_pane"], row_weights=[0,0,0,1,0])
4444
4545 root = tk.Tk()
4646 root.title("Demo of the TkPane Package")
diff -r f082099bdfa7 -r 9f78f82c1a16 tkpane/lib.py
--- a/tkpane/lib.py Wed Mar 14 21:16:06 2018 -0700
+++ b/tkpane/lib.py Sat Mar 17 10:19:09 2018 -0700
@@ -20,11 +20,7 @@
2020 #
2121 #===============================================================================
2222
23-"""A collection of TkPane subclasses that may be used as-is or used as templates
24-for creation of other custom pane classes.
25-"""
26-
27-__version__ = "0.16.0"
23+__version__ = "1.0.0"
2824
2925
3026 try:
@@ -255,7 +251,7 @@
255251 :param height: The height of the Canvas widget, in pixels (optional).
256252 :param config_opts: A dictionary of configuration options for the Canvas widget (optional).
257253
258- Because of the variety of types of information that can be display on a Canvas
254+ Because of the variety of types of information that can be displayed on a Canvas
259255 widget, and associated metadata (e.g., position), the CanvasPane class does
260256 not maintain a data dictionary representing any of that information. Nor
261257 is there any built-in determination of whether the Canvas' contents are valid
@@ -324,7 +320,7 @@
324320 return self.canvaswidget
325321
326322 def set_scrolling(self):
327- """Set the scrollbars to allow scrolling of the entire contents of the Canvas."""
323+ """Set or reset the scrollbar limits to allow scrolling of the entire contents of the Canvas."""
328324 self.canvaswidget.config(scrollregion=self.canvaswidget.bbox(tk.ALL))
329325
330326
@@ -339,6 +335,7 @@
339335 :param config_opts: A dictionary of configuration options for the Checkbutton widget.
340336
341337 Data keys managed by this pane: "check" or the key name specified during initialization.
338+
342339 The value of this item is always True or False, and defaults to False.
343340
344341 Name used by this pane: user-defined on initialization.
@@ -421,7 +418,7 @@
421418 def set_data(self, data):
422419 """Update the pane's data dictionary with the provided data.
423420
424- Special key supported: 'prompt' changes the pane's prompt.
421+ Special key supported: "prompt" changes the pane's prompt.
425422 """
426423 spkey = "prompt"
427424 if spkey in data:
@@ -610,7 +607,7 @@
610607 :param prompt: The prompt to be presented in a Label widget adjacent to the entry.
611608 :param key_name: The name to be used with the internal data dictionary to identify the entry data; use to avoid name conflicts with other EntryPane objects on the same UI (optional).
612609 :param required: A Boolean indicating whether valid data must be entered (optional; default is False).
613- :param blank_is_valid: A Boolean indicating whether, if an entry is not required, a blank value should be treated as a valid entry (optional; default is False).
610+ :param blank_is_valid: A Boolean indicating whether, if an entry is not required, a blank value should be treated as a valid entry (optional; default is False). If this is set to True, an empty string may be passed to any other pane that requires this pane.
614611
615612 Data keys managed by this pane: "entry" or the key name specified during initialization.
616613
@@ -1212,9 +1209,11 @@
12121209 Name used by this pane: "Message".
12131210
12141211 Overridden methods:
1212+
12151213 * set
12161214
12171215 Custom methods:
1216+
12181217 * set_message
12191218 """
12201219 def __init__(self, parent, message):
@@ -1370,21 +1369,28 @@
13701369 self.ok_btn.focus_set()
13711370
13721371 def set_ok_action(self, ok_action):
1373- """Specify the callback function to be called when the 'OK' button is clicked."""
1372+ """Specify the callback function to be called when the "OK" button is clicked.
1373+
1374+ The callback function should take a dictionary as an argument. It will be
1375+ passed the OkCancelPane's entire data dictionary.
1376+ """
13741377 self.ok_action = ok_action if ok_action is not None else do_nothing
13751378 self.ok_btn.configure(command=self.ok_action)
13761379
13771380 def set_cancel_action(self, cancel_action):
1378- """Specify the callback function to be called when the 'Cancel' button is clicked."""
1381+ """Specify the callback function to be called when the "Cancel" button is clicked.
1382+
1383+ The callback function will not be passed any arguments.
1384+ """
13791385 self.cancel_action = cancel_action if cancel_action is not None else do_nothing
13801386 self.cancel_btn.configure(command=self.cancel_action)
13811387
13821388 def ok(self):
1383- """Trigger this pane's 'OK' action. The callback function will be passed this pane's data dictionary."""
1389+ """Trigger this pane's "OK" action. The callback function will be passed this pane's data dictionary."""
13841390 self.ok_action(self.datadict)
13851391
13861392 def cancel(self):
1387- """Trigger this pane's 'Cancel' action."""
1393+ """Trigger this pane's "Cancel" action."""
13881394 self.cancel_action()
13891395
13901396
@@ -1825,11 +1831,11 @@
18251831 """Display a Tkinter Scale widget.
18261832
18271833 :param pane_name: The name to be used to identify this pane in status messages.
1828- :param orientation:
1829- :param length:
1830- :param min_value:
1831- :param max_value:
1832- :param init_value:
1834+ :param orientation: "horizontal" for a horizontal scale bar, otherwise the scale bar will be vertical.
1835+ :param length: Length of the scale bar, in pixels.
1836+ :param min_value: Minimum value for the scale bar.
1837+ :param max_value: Maximum value for the scale bar.
1838+ :param init_value: Initial value for the scale bar.
18331839 :param key_name: The name to be used with the internal data dictionary to identify the entry data; use to avoid name conflicts with other EntryPane objects on the same UI (optional).
18341840 :param config_opts: A dictionary of scale widget configuration options
18351841
@@ -2349,10 +2355,11 @@
23492355 """Update the pane's data dictionary with the provided data.
23502356
23512357 Special keys supported: 'message' and 'table'.
2358+
23522359 * message: Text to replace the message above the table.
23532360 * table: the value should be a two-element tuple, of which the
2354- first element is a list of the column header names and the second is a
2355- list (rows) of lists (columns) containing the table's data.
2361+ first element is a list of the column header names and the second is a
2362+ list (rows) of lists (columns) containing the table's data.
23562363 """
23572364 if "message" in data:
23582365 self.msg_label.configure(text=data["message"])
@@ -2506,10 +2513,11 @@
25062513 """Update the pane's data dictionary with the provided data.
25072514
25082515 Special keys supported: 'message' and 'table'.
2516+
25092517 * message: Text to replace the message above the table.
25102518 * table: the value should be a two-element tuple, of which the
2511- first element is a list of the column header names and the second is a
2512- list (rows) of lists (columns) containing the table's data.
2519+ first element is a list of the column header names and the second is a
2520+ list (rows) of lists (columns) containing the table's data.
25132521 """
25142522 if "message" in data:
25152523 self.msg_label.configure(text=data["message"])
@@ -2591,7 +2599,9 @@
25912599
25922600 :param key_name: The name to be used with the internal data dictionary to identify the text data; use to avoid name conflicts with other TextPane objecs on the same UI (optional).
25932601 :param optiondict: A dictionary of option names and values for initial configuration of the Text widget (optional).
2594- :parame initial_text: Initial contents for the Text widget (optional).
2602+ :param initial_text: Initial contents for the Text widget (optional).
2603+ :param required: A Boolean indicating whether valid data must be entered (optional; default is False).
2604+ :param blank_is_valid: A Boolean indicating whether, if an entry is not required, a blank value should be treated as a valid entry (optional; default is False). If this is set to True, an empty string may be passed to any other pane that requires this pane.
25952605
25962606 Because of the large number of uses of the Text widget, this pane
25972607 provides direct access to the Text widget via the 'textwidget' method.
diff -r f082099bdfa7 -r 9f78f82c1a16 tkpane/tkpane.py
--- a/tkpane/tkpane.py Wed Mar 14 21:16:06 2018 -0700
+++ b/tkpane/tkpane.py Sat Mar 17 10:19:09 2018 -0700
@@ -28,7 +28,7 @@
2828 that pass specific data to allow communication between panes, and callback methods
2929 for reporting status and progress."""
3030
31-__version__ = "0.30.0"
31+__version__ = "1.0.0"
3232
3333
3434 try:
@@ -824,7 +824,7 @@
824824
825825 class LayoutPaneGroup(dict):
826826 def add_element(self, element_name, element):
827- # Add the pane for the given element (if any) as an attribute.
827+ # Add the pane for the given element (if any) as a dictionary item.
828828 fr = element.frame
829829 if fr is not None:
830830 widgets = fr.winfo_children()
@@ -845,11 +845,11 @@
845845
846846
847847 def layout_panes(layout):
848- """Take a tklayout.AppLayout object and return an object that has pane objects as attributes,
848+ """Take a tklayout.AppLayout object and return a dictionary of pane objects with AppLayout identifiers as keys,
849849
850- If the ``tklayout`` package has been used to assemble panes into a UI, this function
851- will collect all of the pane names and corresponding pane objects from the
852- layout object into a single new object. This can simplify access to the pane
850+ If the ``tklayout`` package has been used to assemble panes into a UI, this
851+ function will create and return a dictionary of all of the AppLayout element
852+ names and corresponding pane objects. This can simplify access to the pane
853853 objects for subsequent customization.
854854 """
855855
@@ -860,7 +860,7 @@
860860
861861
862862 def build_ui(layout_spec, tk_parent, ui_root_element, build_specs):
863- """Take specifications for a UI layout and panes, and assemble them, returning an object with the panes as attributes.
863+ """Take specifications for a UI layout and panes, and assemble them, returning a dictionary of panes.
864864
865865 :param layout_spec: A tklayout.AppLayout object for which all of the UI elements have been described.
866866 :param tk_parent: The Tkinter widget (e.g., a frame) that will be the parent widget for the entire UI.
Show on old repository browser