465 replies to this topic

[IanSav]

Hi Prl,

 

Yes, you are the person to whom I was referring.

 

Regards,

Ian.

[Rob van der Does]

--------------------------------------------------------
 
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")
or
self["key_red"].text = _("Close")
 
If you want to temporarily suppress the display of the button use the 
following syntax:
 
self["key_red"].setText("")
or
self["key_red"].text = ""
 
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("")
or
self["key_menu"].text = ""
 
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---[/code]
 
Regards,
Ian.

 
The advantage of placing such a document inside the repos (instead of or in addition to placing it in the WiKi), is that it is available for all teams that pull from PLi. And that in itself is beneficial for all, as it might create less need for individual changes for other teams, which make pushing back (which is so desired by PLi) much more easy!

Edited by Rob van der Does, 23 February 2018 - 15:30.

[WanWizard]

True. The main question is where it will lead too, as you'll end up with a very distributed documentation system, which isn't all that either.

 

Maybe it is be an alternative to maintain a sort of index in the wiki, pointing to public repo's containing the docs, so at least there is a single entry point for people wanting to learn so they can contribute?

[Rob van der Does]

I'm sure that teams who pull from PLi won't read the Wiki first (if they do at all).

[athoik]

I'm sure that teams who pull from PLi won't read the Wiki first (if they do at all).

People respecting other's code, yes they pull and fix merge conficts.

Usually they get code without mentioning OpenPli at all. Or they get code and you never know it (closed source images using our free work).

Edited by athoik, 23 February 2018 - 17:41.

[WanWizard]

I'm sure that teams who pull from PLi won't read the Wiki first (if they do at all).

 

If they pull a repo, they have the docs in that repo. They don't need more.

 

And honestly, I don't really care about those people. The wiki is for people working on (or interested in) OpenPLi development.

[Rob van der Does]

That's why I said
 

And that in itself is beneficial for all, as it might create less need for individual changes for other teams, which make pushing back (which is so desired by PLi) much more easy!

 

 

Which is difficult enough as it is, with the lack of dev-builds.....

 

Oh well, don't bother. But don't ask for 'pushing back' either.....

[athoik]

Oh well, don't bother. But don't ask for 'pushing back' either.....

Pushing back is a matter of attitude... It's not a matter if somebody has access to OpenPLi dev server...

Not long time ago, every commit was available for all users the next morning, back then ... they didn't 'push back' also.

Edited by athoik, 23 February 2018 - 20:10.

[prl]

Hi Huevos,

BTW, guys you do realize certain functions are not available to StaticText()? Which is why the thread started with the question "is there a way to merge the functionality of all three of these class objects".

I gave it a try but was unsuccessful. 

 

If a merge is done, I think the way to go is the reverse of what has been done in Button and Label, where there's currently the DummySource mixin to allow them to be used in source= widgets as well as name= widgets. That is, to make the StaticText source act like a Source if it has downstream elements and to make it act like a GUIComponent if it doesn't. Then Label and Button could be subclassed from StaticText, though I haven't yet looked at how that would work with other subclasses of Label (e.g. LabelConditional/BlinkingLabel/BlinkingLabelConditional/MultiColorLabel).

 

The only method in Label that I've seen that looks like it might be troublesome to implement in a merged StaticText widget is getSize(), where it would have to reach down through the downstream chain to find an object with an instance attribute to get the widget dimensions. That's complicated by the fact that each Element can have multiple downstreams, so there may not be a unique size in general, though I don't think that there is a way of creating multiple branches in the downstreams of Elements. That doesn't, though, rule out someone, somewhere, having created such a thing in code other than skin.py.

 

Also, I'm having trouble reconciling this suggested direction with the object type conditions in IanSav's proposal. If the three types are interchangeable between name= and source= widgets, then there shouldn't be a need for an "objectTypes" widget attribute. The skin author could simply decide that coloured buttons will be skinned as either source= or name= widgets, either once in a template, or on an ad hoc basis that's largely determined by the legacy code's decisions about whether a Source or a GUIComponent was expected.

 

Peter

[prl]

...
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.

 

I think that "If the variable is not defined by one of the types" should be "If the variable is not an instance of one of the types" (in the sense of isinstance(), where subclass instances are considered instances of their superclass) for precision. Perhaps "class" should be used generally in the document rather than "type" or "object type".

[prl]

... I don't think that there is a way of creating multiple branches in the downstreams of Elements. ...

 

That should be "I don't think that there is a way of creating multiple branches in the downstreams of Elements from a skin".

[Huevos]

 

Oh well, don't bother. But don't ask for 'pushing back' either.....

Pushing back is a matter of attitude... It's not a matter if somebody has access to OpenPLi dev server...

Not long time ago, every commit was available for all users the next morning, back then ... they didn't 'push back' also.

 

Yes, but we are not discussing those people. We are talking about it not being so easy for the external developers that have been pushing patches to PLi for a long time.

 

E.g. A person wants to contribute to the OpenPLi skins git (on Littlesat's repo). Those skins will only run on a develop image. On all the other builds the receiver won't even boot. So without access to a develop image contributing to that repo is impossible.

Edited by Huevos, 24 February 2018 - 09:30.

[IanSav]

Hi Prl,

 

If the code refactor happens then the objectType attribute, and its documentation, should go.  It is a band-aid patch on some bad code.

 

Regards,

Ian.

[Huevos]

Lets keep the horse before the carriage. And anyway there are othrr uses for that attribute .

[littlesat]

I agree develop should be made available with limitations.
Wanwizard is working on it,
But it take some time...

[Rob van der Does]

We already discussed the need to have access to dev-builds, and this has been granted (but not yet in place).

 

My point was only that it would be beneficial for all parties to have the button-documentation in the repos, as the (not honoured) pullrequest was about. And as there are no operational consequences, I can't see any reason not to accept that.

[WanWizard]

A bit more patience, please.

 

I have limited time until after next weekend, due to personal circumstances.

[MCelliotG]

I think the new format created more confusion that helped.

In my case, I have a huge problem auto-hiding whatever is in the name= format. I managed to autohide the source= format easily, but the name is impossible for me.

For instance

This template works fine

 <screen name="FullKeys1" flags="wfNoBorder">
 
 <widget objectTypes="key_red,StaticText" source="key_red" render="Label" position="535,855" size="320,90" zPosition="6" font="Regular; 30" halign="center" backgroundColor="background20" transparent="1" valign="bottom" />
 
 <widget objectTypes="key_green,StaticText" source="key_green" render="Label" position="860,855" size="320,90" zPosition="6" font="Regular; 30" halign="center" backgroundColor="background20" transparent="1" valign="bottom" />
  
<widget objectTypes="key_yellow,StaticText" source="key_yellow" render="Label" position="1185,855" size="320,90" zPosition="6" font="Regular; 30" halign="center" backgroundColor="background20" transparent="1" valign="bottom" />

<widget objectTypes="key_blue,StaticText" source="key_blue" render="Label" position="1510,855" size="320,90" zPosition="6" font="Regular; 30" halign="center" backgroundColor="background20" transparent="1" valign="bottom />

 
 <widget objectTypes="key_red,StaticText" source="key_red" render="Pixmap" pixmap="GlamourAuraFHD/buttons/aura_red.png" position="580,870" size="225,75" alphatest="blend" zPosition="5" transparent="1" />
 
 <widget objectTypes="key_green,StaticText" source="key_green" render="Pixmap" pixmap="GlamourAuraFHD/buttons/aura_green.png" position="910,870" size="225,75" alphatest="blend" zPosition="5" transparent="1" />
 
 <widget objectTypes="key_yellow,StaticText" source="key_yellow" render="Pixmap" pixmap="GlamourAuraFHD/buttons/aura_yellow.png" position="1230,870" size="225,75" alphatest="blend" zPosition="5" transparent="1" />
  
<widget objectTypes="key_blue,StaticText" source="key_blue" render="Pixmap" pixmap="GlamourAuraFHD/buttons/aura_blue.png" position="1555,870" size="225,75" alphatest="blend" zPosition="5" transparent="1" />

</screen>

This has a problem with the pngs, it does not autohide them

 <screen name="FullKeys2" flags="wfNoBorder">

  <widget objectTypes="key_red,Button,Label" name="key_red" position="535,855" size="320,90" zPosition="6" font="Regular; 30" halign="center" backgroundColor="background20" transparent="1" valign="bottom" />
  
<widget objectTypes="key_green,Button,Label" name="key_green" position="860,855" size="320,90" zPosition="6" font="Regular; 30" halign="center" backgroundColor="background20" transparent="1" valign="bottom" />
  
<widget objectTypes="key_yellow,Button,Label" name="key_yellow" position="1185,855" size="320,90" zPosition="6" font="Regular; 30" halign="center" backgroundColor="background20" transparent="1" valign="bottom" />
  
<widget objectTypes="key_blue,Button,Label" name="key_blue" position="1510,855" size="320,90" zPosition="6" font="Regular; 30" halign="center" backgroundColor="background20" transparent="1" valign="bottom" />


 
 <ePixmap objectTypes="key_red,Button,Label" pixmap="GlamourAuraFHD/buttons/aura_red.png" position="580,870" size="225,75" alphatest="blend" zPosition="5" transparent="1" />
 
<ePixmap objectTypes="key_green,Button,Label" pixmap="GlamourAuraFHD/buttons/aura_green.png" position="910,870" size="225,75" alphatest="blend" zPosition="5" transparent="1" />
  
<ePixmap objectTypes="key_yellow,Button,Label" pixmap="GlamourAuraFHD/buttons/aura_yellow.png" position="1230,870" size="225,75" alphatest="blend" zPosition="5" transparent="1" />
 
 <ePixmap objectTypes="key_blue,Button,Label" pixmap="GlamourAuraFHD/buttons/aura_blue.png" position="1555,870" size="225,75" alphatest="blend" zPosition="5" transparent="1" />


</screen>

What do I do wrong in the second template?

Edited by MCelliotG, 25 February 2018 - 02:53.

[Rob van der Does]

This is the format that works for me:

    <screen name="ButtonPanel">
        <ePixmap pixmap="buttons/big-red.png" objectTypes="key_red,Button,Label" position="15,682" size="284,40 " zPosition="0" alphatest="blend"/>
        <widget source="key_red" render="Pixmap" pixmap="buttons/big-red.png" objectTypes="key_red,StaticText" position="15,682" size="284,40 " zPosition="0" alphatest="blend">
            <convert type="ConditionalShowHide"/>
        </widget>
        <widget name="key_red" objectTypes="key_red,Label,Button" position="15,688" size="284,26" foregroundColor="grey" backgroundColor="secondBG" transparent="1" zPosition="1" font="Regular;22" halign="center"/>
        <widget source="key_red" render="Label" objectTypes="key_red,Label,StaticText" position="15,688" size="284,26" foregroundColor="grey" backgroundColor="secondBG" transparent="1" zPosition="1" font="Regular;22" halign="center"/>
        <ePixmap pixmap="buttons/big-green.png" objectTypes="key_green,Button,Label" position="305,682" size="284,40" zPosition="0" alphatest="blend"/>
        <widget source="key_green" render="Pixmap" pixmap="buttons/big-green.png" objectTypes="key_green,StaticText" position="305,682" size="284,40 " zPosition="0" alphatest="blend">
            <convert type="ConditionalShowHide"/>
        </widget>
        <widget name="key_green" objectTypes="key_green,Label,Button" position="305,688" size="284,26" foregroundColor="grey" backgroundColor="secondBG" transparent="1" zPosition="1" font="Regular;22" halign="center"/>
        <widget source="key_green" render="Label" objectTypes="key_green,StaticText" position="305,688" size="284,26" foregroundColor="grey" backgroundColor="secondBG" transparent="1" zPosition="1" font="Regular;22" halign="center"/>
        <ePixmap pixmap="buttons/big-yellow.png" objectTypes="key_yellow,Button,Label" position="595,682" size="284,40 " zPosition="0" alphatest="blend"/>
        <widget source="key_yellow" render="Pixmap" pixmap="buttons/big-yellow.png" objectTypes="key_yellow,StaticText" position="595,682" size="284,40 " zPosition="0" alphatest="blend">
            <convert type="ConditionalShowHide"/>
        </widget>
        <widget name="key_yellow" objectTypes="key_yellow,Label,Button" position="595,688" size="284,26" foregroundColor="grey" backgroundColor="secondBG" transparent="1" zPosition="1" font="Regular;22" halign="center"/>
        <widget source="key_yellow" render="Label" objectTypes="key_yellow,StaticText" position="595,688" size="284,26" foregroundColor="grey" backgroundColor="secondBG" transparent="1" zPosition="1" font="Regular;22" halign="center"/>
        <ePixmap pixmap="buttons/big-blue.png" objectTypes="key_blue,Button,Label" position="890,682" size="284,40 " zPosition="0" alphatest="blend"/>
        <widget source="key_blue" render="Pixmap" pixmap="buttons/big-blue.png" objectTypes="key_blue,StaticText" position="890,682" size="284,40 " zPosition="0" alphatest="blend">
            <convert type="ConditionalShowHide"/>
        </widget>
        <widget name="key_blue" objectTypes="key_blue,Label,Button" position="890,688" size="284,26" foregroundColor="grey" backgroundColor="secondBG" transparent="1" zPosition="1" font="Regular;22" halign="center"/>
        <widget source="key_blue" render="Label" objectTypes="key_blue,StaticText" position="890,688" size="284,26" foregroundColor="grey" backgroundColor="secondBG" transparent="1" zPosition="1" font="Regular;22" halign="center"/>
    </screen>

 

[Rob van der Does]

A bit more patience, please.

 

I have limited time until after next weekend, due to personal circumstances.

Accepting a pullrequest that doesn't even have to be checked (as it only pulls in a small document) can't take that much time.