Skip to content

Format code examples in the user documentation #1640

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rahulporuri merged 18 commits into from
May 5, 2021
Merged

Format code examples in the user documentation #1640

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
e2f6da9
CLN : Format code examples in docs
May 3, 2021
a070f64
CLN : Move docs examples into the docs tree
May 3, 2021
f374b49
CLN : Replace array editor with literalinclude in factories basic
May 3, 2021
2944737
CLN : literalinclude enum editor in factories basic
May 3, 2021
aefa4ac
CLN : code formatting in array editor example
May 3, 2021
0ea8f2e
CLN : literalinclude instance editor selection
May 3, 2021
5ac7176
CLN : literalinclude key bindings example
May 3, 2021
51c091b
CLN : literalinclude tree editor example
May 3, 2021
37d2291
CLN : literalinclude wizard and configure_traits_view_buttons
May 3, 2021
2d1208a
CLN : literalinclude default_traits_view and multiple_views
May 3, 2021
d37c329
CLN : literalinclude multi_object_view
May 3, 2021
7c49ae5
CLN : literalinclude configure_traits_view_group
May 3, 2021
d3094e5
CLN : literalinclude configure_traits_view
May 3, 2021
82c895e
CLN : literalinclude handler_override
May 3, 2021
670d09b
FIX : Ignore wizard in integrationtests
May 3, 2021
b37b99e
CLN : Minor formatting issues
May 4, 2021
e37c5bc
CLN : literalinclude default_traits_view2
May 5, 2021
393695c
CLN : minor formatting changes based on PR review
May 5, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 9 additions & 5 deletions docs/source/traitsui_user_manual/adapters.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -208,8 +208,10 @@ such a structure might look like this::
return bool(self.value)

def tno_get_children(self, node):
return [DictNode(parent=self, label=key, value=value)
for key, value in sorted(self.value.items())]
return [
DictNode(parent=self, label=key, value=value)
for key, value in sorted(self.value.items())
]

and so forth. There is additional work if you want to be able to modify
the structure of the tree, for example. In addition to defining the
Expand Down Expand Up @@ -360,9 +362,11 @@ Say instead that you have a list of :py:class:`Person` objects, with
display in the table. Then you could use the following
:py:attr:`~TabularAdapter.columns` value instead::

columns = [('Name', 'name'),
('Age', 'age'),
('Weight', 'weight')]
columns = [
('Name', 'name'),
('Age', 'age'),
('Weight', 'weight'),
]

In this case, the *column ids* are the names of the traits you want to display
in each column.
Expand Down
174 changes: 28 additions & 146 deletions docs/source/traitsui_user_manual/advanced_view.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,30 +63,8 @@ variation on Example 3:

.. rubric:: Example 5: Using configure_traits() with a default View object

::

# default_traits_view.py -- Sample code to demonstrate the use of
# 'traits_view'
from traits.api import HasTraits, Str, Int
from traitsui.api import View, Item, Group
import traitsui

class SimpleEmployee2(HasTraits):
first_name = Str()
last_name = Str()
department = Str()

employee_number = Str()
salary = Int()

traits_view = View(Group(Item(name = 'first_name'),
Item(name = 'last_name'),
Item(name = 'department'),
label = 'Personnel profile',
show_border = True))

sam = SimpleEmployee2()
sam.configure_traits()
.. literalinclude:: examples/default_traits_view.py
:start-at: default_traits_view.py

In this example, configure_traits() no longer requires a *view* keyword
argument; the **traits_view** attribute is used by default, resulting in the
Expand Down Expand Up @@ -115,31 +93,8 @@ example above would be implemented as follows:

.. rubric:: Example 5b: Building a default View object with default_traits_view()

::

# default_traits_view2.py -- Sample code to demonstrate the use of
# 'default_traits_view'
from traits.api import HasTraits, Str, Int
from traitsui.api import View, Item, Group
import traitsui

class SimpleEmployee2(HasTraits):
first_name = Str()
last_name = Str()
department = Str()

employee_number = Str()
salary = Int()

def default_traits_view(self):
return View(Group(Item(name = 'first_name'),
Item(name = 'last_name'),
Item(name = 'department'),
label = 'Personnel profile',
show_border = True))

sam = SimpleEmployee2()
sam.configure_traits()
.. literalinclude:: examples/default_traits_view2.py
:start-at: default_traits_view2.py

This pattern can be useful for situations where the layout of GUI elements
depends on the state of the object. For instance, to populate the values of a
Expand All @@ -165,40 +120,8 @@ this by simply adding a second View attribute:

.. rubric:: Example 6: Defining multiple View objects in a HasTraits class

::

# multiple_views.py -- Sample code to demonstrate the use of
# multiple views
from traits.api import HasTraits, Str, Int
from traitsui.api import View, Item, Group
import traitsui

class SimpleEmployee3(HasTraits):
first_name = Str()
last_name = Str()
department = Str()

employee_number = Str()
salary = Int()

traits_view = View(Group(Item(name = 'first_name'),
Item(name = 'last_name'),
Item(name = 'department'),
label = 'Personnel profile',
show_border = True))

all_view = View(Group(Item(name = 'first_name'),
Item(name = 'last_name'),
Item(name = 'department'),
Item(name = 'employee_number'),
Item(name = 'salary'),
label = 'Personnel database ' +
'entry',
show_border = True))

sam = SimpleEmployee3()
sam.configure_traits()
sam.configure_traits(view='all_view')
.. literalinclude:: examples/multiple_views.py
:start-at: multiple_views.py

.. index:: traits_view attribute, configure_traits(); view parameter

Expand Down Expand Up @@ -240,9 +163,15 @@ UI, you can define a named View wherever you can define a variable or class
attribute. [7]_ A View can even be defined in-line as a function or method
argument, for example::

object.configure_traits(view=View(Group(Item(name='a'),
Item(name='b'),
Item(name='c')))
object.configure_traits(
view=View(
Group(
Item(name='a'),
Item(name='b'),
Item(name='c'),
),
),
)

However, this approach is apt to obfuscate the code unless the View is very
simple.
Expand Down Expand Up @@ -387,55 +316,8 @@ example shows:

.. rubric:: Example 7: Using a multi-object view with a context

::

# multi_object_view.py -- Sample code to show multi-object view
# with context

from traits.api import HasTraits, Str, Int, Bool
from traitsui.api import View, Group, Item

# Sample class
class House(HasTraits):
address = Str()
bedrooms = Int()
pool = Bool()
price = Int()

# View object designed to display two objects of class 'House'
comp_view = View(
Group(
Group(
Item('h1.address', resizable=True),
Item('h1.bedrooms'),
Item('h1.pool'),
Item('h1.price'),
show_border=True
),
Group(
Item('h2.address', resizable=True),
Item('h2.bedrooms'),
Item('h2.pool'),
Item('h2.price'),
show_border=True
),
orientation = 'horizontal'
),
title = 'House Comparison'
)
# A pair of houses to demonstrate the View
house1 = House(address='4743 Dudley Lane',
bedrooms=3,
pool=False,
price=150000)
house2 = House(address='11604 Autumn Ridge',
bedrooms=3,
pool=True,
price=200000)

# ...And the actual display command
house1.configure_traits(view=comp_view, context={'h1':house1,
'h2':house2})
.. literalinclude:: examples/multi_object_view.py
:start-at: multi_object_view.py

.. FIXME: This is a bit assymmetrical. Can we clean it up without complicating
the example overly?
Expand Down Expand Up @@ -505,21 +387,21 @@ the following two definitions, taken together, are equivalent to the third:
::

# This fragment...
my_view = View(Group(Item('a'),
Item('b')),
Include('my_group'))
my_view = View(
Group(Item('a'), Item('b')),
Include('my_group'),
)

# ...plus this fragment...
my_group = Group(Item('c'),
Item('d'),
Item('e'))
my_group = Group(
Item('c'), Item('d'), Item('e'),
)

#...are equivalent to this:
my_view = View(Group(Item('a'),
Item('b')),
Group(Item('c'),
Item('d'),
Item('e'))
my_view = View(
Group(Item('a'), Item('b')),
Group(Item('c'), Item('d'), Item('e')),
)

This opens an interesting possibility when a View is part of a model class: any
Include objects belonging to that View can be defined differently for different
Expand Down
67 changes: 10 additions & 57 deletions docs/source/traitsui_user_manual/custom_view.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,35 +101,8 @@ pages that a user must navigate sequentially.

.. rubric:: Example 3.1: Displaying a view the "wizard" style

::

# wizard.py ---Example of a traits-based wizard UI

from traits.api import HasTraits, Str
from traitsui.api import Item, View, VGroup

class Person(HasTraits):
first_name = Str()
last_name = Str()

company = Str()
position = Str()

view = View(
VGroup(
Item("first_name"),
Item("last_name")
),
VGroup(
Item("company"),
Item("position")
)
)

person = Person(first_name='Postman', last_name='Pat', company="Enthought",
position="Software Developer")
person.configure_traits(kind='wizard')

.. literalinclude:: examples/wizard.py
:start-at: wizard.py

leads to the following 2 modal dialogs:

Expand Down Expand Up @@ -194,30 +167,8 @@ Consider the following variation on Example 3:

.. rubric:: Example 4: Using a View object with buttons

::

# configure_traits_view_buttons.py -- Sample code to demonstrate
# configure_traits()

from traits.api import HasTraits, Str, Int
from traitsui.api import View, Item
from traitsui.menu import OKButton, CancelButton

class SimpleEmployee(HasTraits):
first_name = Str()
last_name = Str()
department = Str()

employee_number = Str()
salary = Int()

view1 = View(Item(name = 'first_name'),
Item(name = 'last_name'),
Item(name = 'department'),
buttons = [OKButton, CancelButton])

sam = SimpleEmployee()
sam.configure_traits(view=view1)
.. literalinclude:: examples/configure_traits_view_buttons.py
:start-at: configure_traits_view_buttons.py

The resulting window has the same content as before, but now two buttons are
displayed at the bottom: :guilabel:`OK` and :guilabel:`Cancel`:
Expand Down Expand Up @@ -257,16 +208,18 @@ from traitsui.menu and assigned to the buttons attribute:

.. index:: OKCancelsButtons, ModalButtons, LiveButtons

* OKCancelButtons = ``[OKButton, CancelButton ]``
* ModalButtons = ``[ ApplyButton, RevertButton, OKButton, CancelButton, HelpButton ]``
* LiveButtons = ``[ UndoButton, RevertButton, OKButton, CancelButton, HelpButton ]``
* OKCancelButtons = ``[OKButton, CancelButton]``
* ModalButtons = ``[ApplyButton, RevertButton, OKButton, CancelButton, HelpButton]``
* LiveButtons = ``[UndoButton, RevertButton, OKButton, CancelButton, HelpButton]``

Thus, one could rewrite the lines in Example 4 as follows, and the
effect would be exactly the same::

from traitsui.menu import OKCancelButtons

buttons = OKCancelButtons
...
buttons=OKCancelButtons,
)

.. index:: NoButtons

Expand Down
42 changes: 42 additions & 0 deletions docs/source/traitsui_user_manual/examples/array_editor.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# (C) Copyright 2004-2021 Enthought, Inc., Austin, TX
Copy link
Copy Markdown
Contributor

@aaronayres35 aaronayres35 May 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should almost definitely end up in traitsui/examples/demo/StandardEditors

# All rights reserved.
#
# This software is provided without warranty under the terms of the BSD
# license included in LICENSE.txt and may be redistributed only under
# the conditions described in the aforementioned license. The license
# is also available online at http://www.enthought.com/licenses/BSD.txt
#
# Thanks for using Enthought open source!

# array_editor.py -- Example of using array editors

import numpy as np

from traits.api import Array, HasPrivateTraits
from traitsui.api import ArrayEditor, Item, View
from traitsui.menu import NoButtons


class ArrayEditorTest(HasPrivateTraits):

three = Array(np.int, (3, 3))

four = Array(
np.float, (4, 4), editor=ArrayEditor(width=-50),
)

view = View(
Item('three', label='3x3 Integer'),
'_',
Item('three', label='Integer Read-only', style='readonly'),
'_',
Item('four', label='4x4 Float'),
'_',
Item('four', label='Float Read-only', style='readonly'),
buttons=NoButtons,
resizable=True,
)


if __name__ == '__main__':
ArrayEditorTest().configure_traits()
Loading