Smart Buttons and Button Panels...

[IanSav]

Hi All,

I have recently been involved with some efforts across OpenPLi and OpenViX to standardise the colour buttons in Enigma2. The discussion has also extended to automating the other action buttons in the user interface.

Work on the colour button changes is well advanced. I have filed Pull Request #420 to add the same facilities to Beyonwiz as is now available on OpenViX and OpenPLi. I have also filed a couple of tidy up requests (Pull Request #418 and Pull Request #419 to revert some of the old changes we made to stop some trivial skin errors. These changes aren't needed with current skin changes. More of these changes should be made but I am hoping that PeterU may be able to achieve the clean up during the next upstream merge.)

I have prepared some documentation on how to implement the current / standard colour buttons and how to achieve these new automated buttons. The idea is to encourage all coder writers and skin developers to use compatible variable names and data structures to make more code and skins interchangeable.

I would like input on the proposal from the Beyonwiz camp. Improvements and corrections are welcome. I should note that these changes are starting to roll out in OpenViX already.

EDIT: Attachment removed an updated in a later post.

Regards,
Ian.

[peteru]

Even though I have not read the document yet, I'm including the text of the attachment inline for convenience...

Code: Select all

Proposal for Standardised and Uniform Buttons in Enigma2
--------------------------------------------------------

Written by IanSav - 12-Feb-2018

INTRODUCTION:
=============

Enigma2 is a massive open source project that has many contributors and 
add-ons.  Over time a number of approaches to performing common tasks have 
evolved.  This document proposes to nominate some conventions that can be 
adopted by all developers, contributors and skin authors to ensure that 
everyone can work independently but still achieve results that work together 
interchangably.

The purpose of this document is to propose some standard variable names 
together with code and skin coding conventions to make the task of creating 
code that works more universally with skins easier.

Button names should be drawn from the current button definitions in 
"keyids.py".  The names used should be the lower case version of the button 
names in this file.  For example, if you wish to define a button for the RED 
button on the remote control then use a variable name of "key_red".

Having used the example of the RED button on the remote control let us look 
at how the red button should be defined in the Python code and how it can be 
rendered in a skin.

COLOUR BUTTONS:
===============

In the Python code to define a RED button to be available in the skin simply 
add the following to your code:

	from Components.Sources.StaticText import StaticText

	self["key_red"] = StaticText(_("Cancel"))

The text should be language translated with the _("text") syntax.  The text 
itself should be as short as practical but clear enough to convey the 
meaning of the button.

During the execution of the code the meaning of the button can easily be 
changed by using the .setText() method.  For example:

	self["key_red"].setText(_("Close")

If you want to temporarily suppress the display of the button use the 
following syntax:

	self["key_red"].setText()

NOTE: Never translate an empty string, _(""), as this causes the translation 
system to output translation engine information and NOT a blank string as 
some may expect.

Now that the code is RED button enabled we need to code the skin to match.  
Here is a skin fragment that supports the code above:

	<screen name="TemplateButtonRed">
		<widget source="key_red" render="Pixmap" \
			pixmap="buttons/button_red.png" position="10,10" \
			size="200,30" alphatest="blend" conditional="key_red" \
			transparent="1">
 			<convert type="ConditionalShowHide" />
 		</widget>
		<widget source="key_red" render="Label" position="10,10" \
			size="200,30" backgroundColor="ButtonRed" \
			font="ButtonFont;20" foregroundColor="ButtonText" \
			halign="center" conditional="key_red" transparent="1" \
			valign="center" zPosition="+1" />
	</screen>

This definition would work well if all the code in Enigma2 was uniform and 
co-ordinated.  Unfortunately we aren't there yet.  A more real world example 
of how to define the button in a skin would be:

	<screen name="TemplateButtonRed">
		<ePixmap pixmap="buttons/button_red.png" position="10,10" \
			size="200,30" alphatest="blend" \
			objectTypes="key_red,Button,Label" transparent="1" />
		<widget source="key_red" render="Pixmap" \
			pixmap="buttons/button_red.png" position="10,10" \
			size="200,30" alphatest="blend" \
			objectTypes="key_red,StaticText" transparent="1">
 			<convert type="ConditionalShowHide" />
 		</widget>
		<widget name="key_red" position="10,10" size="200,30" \
			backgroundColor="ButtonRed" font="ButtonFont;20" \
			foregroundColor="ButtonText" halign="center" \
			objectTypes="key_red,Button,Label" transparent="1" \
			valign="center" zPosition="+1" />
		<widget source="key_red" render="Label" position="10,10" \
			size="200,30" backgroundColor="ButtonRed" \
			font="ButtonFont;20" foregroundColor="ButtonText" \
			halign="center" objectTypes="key_red,StaticText" \
			transparent="1" valign="center" zPosition="+1" />
	</screen>

You will note that the button background image and the button text are 
defined twice.  This allows all legacy code that uses either Button(), 
Label() or StaticText() objects to define the code will still work in this 
proposed skin.  To make this work recent builds of OpenViX,OpenPLi and 
Beyonwiz firmware have added a new attribute to the skin parser.  This new 
attribute is "objectTypes".

The "objectTypes" attribute has a value consisting of a comma separated list 
of keywords.  Note that spaces around the comma(s) are NOT permitted.  The 
first value in the list must be the variable being checked, in this case 
"key_red".  This item is mandatory.  The following values are object type 
definitions of which this variable can be defined for this widget to be 
used.  The list can have zero or more object types listed.

The first value, the variable name, is processed in the same way as the 
conditional attribute.  If the variable is defined in the code then this 
screen widget is enabled and available for use.  If the variable is not 
defined in the code then this widget is ignored.

The following values arguments are a list of object types, like Button, 
Label or StaticText, the variable name's definition type is checked against 
the supplied list.  If the variable is not defined by one of the types in 
the list then that widget is ignored.  If there is a type match then the 
widget is enabled and available for use.  If no object types are listed then 
the "objectTypes" attribute works exactly the same as the "conditional" 
attribute.

ACTION BUTTONS:
===============

Just like the colour buttons there are a number of standard action or 
functiuonal buttons used.  Typically these buttons are defined in the 
various screens for which they are used.  This places a heavy burdon on 
skin writers to determine when the various action buttons are defined and 
available for use and hence when they need to include definitions for those 
buttons in their skin.

As with the colour buttons is is quite easy to automate the inclusion of 
these standard action buttons in both the Pytone code and skin.

Let us use the example of the MENU button on the remote control let us look 
at how the red button should be defined in the Python code and how it can be 
rendered in a skin.

The Python code is exactly the same as that used by the colour button 
example above.  In the Python code to define a MENU button to be available 
in the skin simply add the following to your code:

	from Components.Sources.StaticText import StaticText

	self["key_menu"] = StaticText(_("MENU"))

The text for each action button should be language translated with the 
_("text") syntax.  The text itself should be as short as practical but clear 
enough to convey the meaning of the button.

If you want to temporarily suppress the display of the button use the 
following syntax:

	self["key_menu"].setText()

NOTE: Never translate an empty string, _(""), as this causes the translation 
system to output translation engine information and NOT a blank string as 
some may expect.

Now that the code is MENU button enabled we need to code the skin to match.  
There are two ways a skin designer may choose to display the action buttons.  
They may wish to use a graphical image or they may chose to use a textural 
representation.

Here is a skin fragment that supports the code above to display a graphical 
MENU button:

	<screen name="TemplateButtonMenu">
		<widget source="key_menu" render="Pixmap" \
			pixmap="buttons/button_menu.png" position="0,0" \
			size="50,30" alphatest="blend" conditional="key_menu" \
			transparent="1">
 			<convert type="ConditionalShowHide" />
 		</widget>
	</screen>

Here is a skin fragment that supports the code above to display a textural 
MENU button:

	<screen name="TemplateButtonMenu">
		<widget source="key_menu" render="Label" position="0,0" \
			size="50,30" backgroundColor="ButtonBackground" \
			font="ButtonFont;20" foregroundColor="ButtonText" \
			halign="center" conditional="key_menu" transparent="1" \
			valign="center" zPosition="+1" />
	</screen>

CONCLUSION:
===========

For all the Enigma2 builds there is a significant legacy of code and skins 
that needs to be preserved and protected. The proposal outlined what I 
believe to be a conservative approach to making a significant but beneficial 
change in unifying and standardising the display of action and colour buttons 
across the Enigma2 UI.

---END---

         1         2         3         4         5         6         7         8
12345678901234567890123456789012345678901234567890123456789012345678901234567890

[peteru]

I've been scratching my head looking at the pull requests and wondering how it's actually meant to be used in practice. Hopefully this document will explain it.

[IanSav]

Hi PeterU,

I've been scratching my head looking at the pull requests and wondering how it's actually meant to be used in practice. Hopefully this document will explain it.

If it doesn't explain it well enough then please suggest how the documentation can be improved. The code I submitted was actually a collaboration between OpenPLi and OpenViX. I offered them Prl's code to address the overlapped button issue but they rejected it. This was their accepted resolution. I still consider it a bit of a hack but they want to go with this resolution.

One more appropriate solution could be to remove the hack made in about 2012-2013 that tried to make Button() and Label() objects partially implement the render pipeline. The implementation was incomplete such that the initial text is synchronised but .setText() updates are not. The Button() and Label() objects shouldn't interfere with StaticText() objects at all. If this were so then when a StaticText() object is overlapped with a Button() or Label() object there would be NO overlapped text conflict.

A better solution would be to combine the Button(), Label() and StaticText() objects into a SINGLE object whose role is to pass test to the UI for display. The decision of whether or not to render the item as a simple text string via a "name=" widget or a "source=" render pipeline with potential converter stages should only be made in the skin itself. The code writer should not have to worry about or deal with how the skin author would like to process the display of the text. This solution would be easier to understand, cleaner to implement and would reduce the amount of bloat and rot in the code. Unfortunately my understanding of this area of the code is insufficient to achieve this task. I believe that this solution would be accepted by both OpenViX and OpenPLi if it can be developed, tested and proven to work. The current Button(), Label() and StaticText() objects could simply become subclass redefinitions of this new display class. This should keep all legacy code running while coders switch over to the new class. When adoption is complete then the bridge code can be removed and more bloat can be removed before becoming rot.

Regards,
Ian.

[IanSav]

Hi All,

Here is the latest draft of the document:

Code: Select all

Proposal for Standardised and Uniform Buttons in Enigma2
--------------------------------------------------------

Written by IanSav - 12-Feb-2018
Updated by IanSav - 13-Feb-2018

INTRODUCTION:
=============

Enigma2 is a massive open source project that has many contributors and 
add-ons.  Over time a number of approaches to performing common tasks have 
evolved.  This document proposes to nominate some conventions that can be 
adopted by all developers, contributors and skin authors to ensure that 
everyone can work independently but still achieve results that work together 
interchangeably.

The purpose of this document is to propose some standard variable names 
together with code and skin coding conventions to make the task of creating 
code that works more universally with skins easier.

Button names should be drawn from the current button definitions in 
"keyids.py".  The names used should be the lower-case version of the button 
names in this file.  For example, if you wish to define a button for the RED 
button on the remote control then use a variable name of "key_red".  In 
Enigma2 the four colour buttons should be named "key_red", "key_green", 
"key_yellow" and "key_blue".

As an example, let us look at how the red button should be defined in the 
Python code and how it can be rendered in a skin.

COLOUR BUTTONS:
===============

In the Python code to define a RED button to be available in the skin simply 
add the following to your code:

	from Components.Sources.StaticText import StaticText

	self["key_red"] = StaticText(_("Cancel"))

The text should be language translated with the _("text") syntax.  The text 
itself should be as short as practical but clear enough to convey the 
meaning of the button.

During the execution of the code the meaning of the button can easily be 
changed by using the .setText() method.  For example:

	self["key_red"].setText(_("Close")

If you want to temporarily suppress the display of the button use the 
following syntax:

	self["key_red"].setText()

NOTE: Never translate an empty string, _(""), as this causes the translation 
system to output translation engine information and NOT a blank string as 
some may expect.

Now that the code is RED button enabled we need to code the skin to match.  
Here is a skin fragment that supports the code above:

	<screen name="TemplateButtonRed">
		<widget source="key_red" render="Pixmap" \
			pixmap="buttons/button_red.png" position="10,10" \
			size="200,30" alphatest="blend" conditional="key_red" \
			transparent="1">
 			<convert type="ConditionalShowHide" />
 		</widget>
		<widget source="key_red" render="Label" position="10,10" \
			size="200,30" backgroundColor="ButtonRed" \
			font="ButtonFont;20" foregroundColor="ButtonText" \
			halign="center" conditional="key_red" transparent="1" \
			valign="center" zPosition="+1" />
	</screen>

The first widget checks if the variable "key_red" is defined in this screen 
via the "conditional" attribute.  If "key_red" is defined and not blank the 
image "buttons/button_red.png" is displayed on the screen.  The next widget 
also checks for the existence of "key_red" and then displays the button text 
over the image background.  Please note that a button image background is 
common but it is NOT required.  This is a design choice available to the 
skin author.

This sample would work well if all the code in Enigma2 was uniform and 
co-ordinated.  Unfortunately, we aren't there yet.  A more real-world example 
of how to define the button in a skin would be:

	<screen name="TemplateButtonRed">
		<ePixmap pixmap="buttons/button_red.png" position="10,10" \
			size="200,30" alphatest="blend" \
			objectTypes="key_red,Button,Label" transparent="1" />
		<widget source="key_red" render="Pixmap" \
			pixmap="buttons/button_red.png" position="10,10" \
			size="200,30" alphatest="blend" \
			objectTypes="key_red,StaticText" transparent="1">
 			<convert type="ConditionalShowHide" />
 		</widget>
		<widget name="key_red" position="10,10" size="200,30" \
			backgroundColor="ButtonRed" font="ButtonFont;20" \
			foregroundColor="ButtonText" halign="center" \
			objectTypes="key_red,Button,Label" transparent="1" \
			valign="center" zPosition="+1" />
		<widget source="key_red" render="Label" position="10,10" \
			size="200,30" backgroundColor="ButtonRed" \
			font="ButtonFont;20" foregroundColor="ButtonText" \
			halign="center" objectTypes="key_red,StaticText" \
			transparent="1" valign="center" zPosition="+1" />
	</screen>

The difference here is that the button background image and the button 
text is defined twice.  This allows all legacy code that uses either 
Button(), Label() or StaticText() objects to define the code will still 
work in this proposed skin fragment.  The data from each of the object 
types is displayed overlapped on the screen.  To make this work without 
actually overlapping the data recent builds of OpenViX, OpenPLi and 
Beyonwiz firmware have added a new attribute to the skin parser.  This 
new attribute is "objectTypes".

The "objectTypes" attribute has a value consisting of a comma separated list 
of keywords.  Note that spaces around the comma(s) are NOT permitted.  The 
first value in the list must be the variable being checked, in this case 
"key_red".  This item is mandatory.  The following values are object type 
definitions of which this variable can be defined for this widget to be 
used.  The list can have zero or more object types listed.

The first value, the variable name, is processed in the same way as the 
conditional attribute.  If the variable is defined in the code then this 
screen widget is enabled and available for use.  If the variable is not 
defined in the code then this widget is ignored.

The following values arguments are a list of object types, like Button, 
Label or StaticText, the variable name's definition type is checked against 
the supplied list.  If the variable is not defined by one of the types in 
the list then that widget is ignored.  If there is a type match then the 
widget is enabled and available for use.  If no object types are listed then 
the "objectTypes" attribute works exactly the same as the "conditional" 
attribute.

IMPORTANT NOTE: The latter form of the skin XML code should be used to 
maintain backward compatibility with all existing Python code.  At some 
point in the future when all code is updated to support and comply with 
this proposal then the former, and simpler, version of the skin definition 
can be used as backward compatibility would no longer be an issue.

ACTION BUTTONS:
===============

Just like the colour buttons there are a number of standard action or 
functional buttons used.  For example, MENU, INFO, TEXT, HELP etc. 
Typically, these buttons are manually added / defined by skin writers 
in the various screens for which they are used.  This requirement places 
a heavy burden on skin writers who have to explore the Python code to 
determine when the various action buttons are defined and available for 
use.  If the buttons are defined then there should be definitions for those 
buttons in their skin.

As with the colour buttons it is quite easy to automate the inclusion of 
these standard action buttons in both the Python code and skin.

Let us use the example of the MENU button on the remote control let us look 
at how the red button should be defined in the Python code and how it can be 
rendered in a skin.

The Python code is exactly the same as that used by the colour button 
example above.  In the Python code to define a MENU button to be available 
in the skin simply add the following to your code:

	from Components.Sources.StaticText import StaticText

	self["key_menu"] = StaticText(_("MENU"))

The text for each action button should be language translated with the 
_("text") syntax.  The text itself should be as short as practical but clear 
enough to convey the meaning of the button.

If you want to temporarily suppress the display of the button use the 
following syntax:

	self["key_menu"].setText()

NOTE: Never translate an empty string, _(""), as this causes the translation 
system to output translation engine information and NOT a blank string as 
some may expect.

Now that the code is MENU button enabled we need to code the skin to match.  
There are two ways a skin designer may choose to display the action buttons.  
They may wish to use a graphical image or they may choose to use a text 
based representation.

Here is a skin fragment that supports the code above to display a graphical 
MENU button:

	<screen name="TemplateButtonMenu">
		<widget source="key_menu" render="Pixmap" \
			pixmap="buttons/button_menu.png" position="0,0" \
			size="50,30" alphatest="blend" conditional="key_menu" \
			transparent="1">
 			<convert type="ConditionalShowHide" />
 		</widget>
	</screen>

In this example the widget checks if the variable "key_menu" is defined in 
this screen via the "conditional" attribute.  If "key_menu" is defined and 
not blank the image "buttons/button_menu.png" is displayed on the screen.

Here is a skin fragment that supports the code above to display a textural 
MENU button:

	<screen name="TemplateButtonMenu">
		<widget source="key_menu" render="Label" position="0,0" \
			size="50,30" backgroundColor="ButtonBackground" \
			font="ButtonFont;20" foregroundColor="ButtonText" \
			halign="center" conditional="key_menu" transparent="1" \
			valign="center" zPosition="+1" />
	</screen>

This works the same way as the previous example except that instead of an 
image being displayed on the screen the translated text defined in the Python 
code is displayed on the screen.

CONCLUSION:
===========

For all the Enigma2 builds there is a significant legacy of code and skins 
that needs to be preserved and protected. The proposal outlined what I 
believe to be a conservative approach to making a significant but beneficial 
change in unifying and standardising the display of action and colour buttons 
across the Enigma2 UI.

---END---

Regards,
Ian.

[peteru]

What has changed? I see that you have done some proofreading and a bit more may be in order. As an example, textural -> textual

[IanSav]

Hi PeterU,

What has changed? I see that you have done some proofreading and a bit more may be in order. As an example, textural -> textual

OpenPLi and OpenViX reviewers asked for more explanation of the information provided. I also enumerated the colour buttons and offered suggestions for some of the most common action buttons.

"textural" now replaced by "text based". Thanks.

Regards,
Ian.

[prl]

I'd prefer to see the usage button.text = _("something") rather than button.setText(_("something")) being used for examples. And button.text = "" (or perhaps button.text = None) to clear the text.

And perhaps more importantly, do not use button.setText() (i.e. without an argument) in Beyonwiz code without changing Components/Sources/StaticText.py, because its setText() method does not have a default parameter value for the text argument. If that's the same in OpenViX and OpenPLi, then it's probably not a good idea to use that form in the documentation, either, and if button.setText() is to be used in examples, then either button.setText("") or button.setText(None) should be used in the examples unless StaticText.setText() is changed. The same applies for other Components that inherit from VariableText.

Also, the current implementation of Components.Sources.StaticText does not implement a boolean property or attribute, which is referenced by ConditionalShowHide.calcVisibility().

[IanSav]

Hi Prl,

I'd prefer to see the usage button.text = _("something") rather than button.setText(_("something")) being used for examples. And button.text = "" (or perhaps button.text = None) to clear the text.

I was trying to keep the examples simple so that they could be followed easily by using a syntax with which most of the developers are familiar. I will add the alternate syntax to highlight the option. Thank you for the suggestion.

And perhaps more importantly, do not use button.setText() (i.e. without an argument) in Beyonwiz code without changing Components/Sources/StaticText.py, because its setText() method does not have a default parameter value for the text argument. If that's the same in OpenViX and OpenPLi, then it's probably not a good idea to use that form in the documentation, either, and if button.setText() is to be used in examples, then either button.setText("") or button.setText(None) should be used in the examples unless StaticText.setText() is changed. The same applies for other Components that inherit from VariableText.

Thank you for this comment. One of the OpenPLi devs just notified me of the error and the master document has been corrected to use .setText(""). This was a documentation error and not my intention.

Also, the current implementation of Components.Sources.StaticText does not implement a boolean property or attribute, which is referenced by ConditionalShowHide.calcVisibility().

This has been added in the pending Pull Request #420 to add the feature to the Beyonwiz build. It will also arrive via any appropriate upstream merges from OpenViX or OpenPLi.

Regards,
Ian.

[prl]

OK, thanks.

Otherwise it looks like a clean way to manage things.

I'm not sure about using the name "variable" for "key_red", since it isn't, really, but I haven't been able to think of a good alternative. "Widget/source name" is too clunky.

[IanSav]

Hi Prl,

I'm not sure about using the name "variable" for "key_red", since it isn't, really, but I haven't been able to think of a good alternative. "Widget/source name" is too clunky.

I need to be careful with the language I use as many of the audience do not use English as their first language. So far those with a better grasp of English are explaining the document to those who don't.

The proposal seems to be gaining acceptance. Many skins are already being changed and hot discussion is occurring to ensure code updates will happen to bring the code into line.

Regards,
Ian.

[IanSav]

Hi,

The final version of the document has been submitted as pull requests for OpenPLi, OpenViX and Beyonwiz. It has already been merged in OpenViX and is going to be accepted in OpenPLi.

People are already starting to adopt the standardised button proposals.

Regards,
Ian.