Projects/Plasma/PIG: Difference between revisions
< Projects
No edit summary |
|||
| (18 intermediate revisions by 6 users not shown) | |||
| Line 1: | Line 1: | ||
== What These Guidelines (Will) Cover == | == What These Guidelines (Will) Cover == | ||
| Line 5: | Line 7: | ||
== Category Names == | == Category Names == | ||
The following are acceptable known entries for plasmoids and applets. If your applet does not fall within one of the following categories, leave the category field empty (it will be automatically | The following are acceptable known entries for plasmoids and applets. If your applet does not fall within one of the following categories, leave the category field empty (it will be automatically categorized under "Miscellaneous" for the time being) and contact the Plasma development team to have a suitable category added to the list (at which point you may then use that category). | ||
*'''Accessibility''' tools that help those with special needs or disabilities use their computer | |||
*'''Application Launchers''' application starters and file openers. | |||
*'''Astronomy''' anything to do with the night sky or other celestial bodies. | |||
*'''Date and Time''' clocks, calendars, scheduling, etc | *'''Date and Time''' clocks, calendars, scheduling, etc | ||
*'''Environment | *'''Development Tools''' tools and utilities to aid software developers | ||
*'''Education''' teaching and educational aides | |||
*'''Environment and Weather''' add-ons that display information regarding the weather or other environmentally related data | |||
*'''Examples''' samples that are not meant for production systems | *'''Examples''' samples that are not meant for production systems | ||
*'''File System''' anything that operates on files or the file system as it's primary purpose, such as file watchers or directory listings. Simply using a file as storage does not qualify the add-on for this category. | *'''File System''' anything that operates on files or the file system as it's primary purpose, such as file watchers or directory listings. Simply using a file as storage does not qualify the add-on for this category. | ||
*'''Fun and Games''' for games and amusements | |||
*'''Graphics''' for add-ons where displaying images, photos or graphical eye candy is the primary purpose | *'''Graphics''' for add-ons where displaying images, photos or graphical eye candy is the primary purpose | ||
*'''Language''' add-ons whose primary purpose is language related, such as dictionaries and translators. | *'''Language''' add-ons whose primary purpose is language related, such as dictionaries and translators. | ||
*'''Mapping''' geography and geographic data add-ons | *'''Mapping''' geography and geographic data add-ons | ||
*'''Multimedia''' music and video. | |||
*'''Online Services''' add-ons that provide an interface to online services such as social networking or blogging sites. If there is another more appropriate category for the add-on given the topic (e.g. mapping if the applet's purpose is to show maps), even if the data is retrieved from the Internet prefer that other category over this one. | *'''Online Services''' add-ons that provide an interface to online services such as social networking or blogging sites. If there is another more appropriate category for the add-on given the topic (e.g. mapping if the applet's purpose is to show maps), even if the data is retrieved from the Internet prefer that other category over this one. | ||
*'''System Information''' display and interaction with information about the computer such as network activity, hardware health, memory usage, etc | *'''System Information''' display and interaction with information about the computer such as network activity, hardware health, memory usage, etc | ||
*'''Utilities''' Useful tools like calculators | |||
*'''Windows and Tasks''' managers for application windows and/or tasks, such as taskbars | *'''Windows and Tasks''' managers for application windows and/or tasks, such as taskbars | ||
== Theming == | == Theming == | ||
| Line 34: | Line 37: | ||
== Packaging Conventions == | == Packaging Conventions == | ||
=== Unique Naming === | |||
Since your plugins and packages will co-exist with everyone else's, it is a good idea to use a naming scheme that eliminates possibility of accidental name collisions. | |||
In the examples below where it referse to [name], consider including an element unique to your project or organization in it. For instance, if your packages accompany an application, consider including the name of the application. Using an organizational or domain name are also possibilities. | |||
For example, if your plasmoid was called "SuperWidget", the [name] might be: | |||
* myapp_superwidget if it comes with the MyApp program | |||
* myorg_superwidget if it is associated with the MyOrg project/company/entity | |||
* net_myorg_foo_superwidget if the domain name associated with the plasmoid's origin is foo.myorg.net | |||
=== .desktop Files === | |||
Plasma uses a "general to specific" naming system for .desktop files. Following this practice makes it easy to find entries in the file system and keeps things nicely ordered. | |||
In the list below, [name] would most commonly be the plugin name as found in the file. Files autogenerated by ScriptEngines may include additional namespacing information in the file name. | |||
* Animators: plasma-animator-[name].desktop | |||
* Applets: plasma-applet-[name].desktop. Does not matter what language it is implemented in, it should always have the plasma-applet prefix. | |||
* Containments: plasma-containment-[name].desktop | |||
* DataEngines: plasma-dataengine-[name].desktop | |||
* Runners: plasma-runner-[name].desktop | |||
* ScriptEngines: plasma-scriptengine-[type]-[name].desktop where type may be one or more of Applet, DataEngine and/or Runner. | |||
Latest revision as of 09:27, 14 July 2012
What These Guidelines (Will) Cover
This document is a place to collect all the "do"s, "don't"s and "how to"s for interface elements in Plasma, particularly applets and plasmoids.
Category Names
The following are acceptable known entries for plasmoids and applets. If your applet does not fall within one of the following categories, leave the category field empty (it will be automatically categorized under "Miscellaneous" for the time being) and contact the Plasma development team to have a suitable category added to the list (at which point you may then use that category).
- Accessibility tools that help those with special needs or disabilities use their computer
- Application Launchers application starters and file openers.
- Astronomy anything to do with the night sky or other celestial bodies.
- Date and Time clocks, calendars, scheduling, etc
- Development Tools tools and utilities to aid software developers
- Education teaching and educational aides
- Environment and Weather add-ons that display information regarding the weather or other environmentally related data
- Examples samples that are not meant for production systems
- File System anything that operates on files or the file system as it's primary purpose, such as file watchers or directory listings. Simply using a file as storage does not qualify the add-on for this category.
- Fun and Games for games and amusements
- Graphics for add-ons where displaying images, photos or graphical eye candy is the primary purpose
- Language add-ons whose primary purpose is language related, such as dictionaries and translators.
- Mapping geography and geographic data add-ons
- Multimedia music and video.
- Online Services add-ons that provide an interface to online services such as social networking or blogging sites. If there is another more appropriate category for the add-on given the topic (e.g. mapping if the applet's purpose is to show maps), even if the data is retrieved from the Internet prefer that other category over this one.
- System Information display and interaction with information about the computer such as network activity, hardware health, memory usage, etc
- Utilities Useful tools like calculators
- Windows and Tasks managers for application windows and/or tasks, such as taskbars
Theming
Animation
Configuration
Status Notifications
Packaging Conventions
Unique Naming
Since your plugins and packages will co-exist with everyone else's, it is a good idea to use a naming scheme that eliminates possibility of accidental name collisions.
In the examples below where it referse to [name], consider including an element unique to your project or organization in it. For instance, if your packages accompany an application, consider including the name of the application. Using an organizational or domain name are also possibilities.
For example, if your plasmoid was called "SuperWidget", the [name] might be:
- myapp_superwidget if it comes with the MyApp program
- myorg_superwidget if it is associated with the MyOrg project/company/entity
- net_myorg_foo_superwidget if the domain name associated with the plasmoid's origin is foo.myorg.net
.desktop Files
Plasma uses a "general to specific" naming system for .desktop files. Following this practice makes it easy to find entries in the file system and keeps things nicely ordered.
In the list below, [name] would most commonly be the plugin name as found in the file. Files autogenerated by ScriptEngines may include additional namespacing information in the file name.
- Animators: plasma-animator-[name].desktop
- Applets: plasma-applet-[name].desktop. Does not matter what language it is implemented in, it should always have the plasma-applet prefix.
- Containments: plasma-containment-[name].desktop
- DataEngines: plasma-dataengine-[name].desktop
- Runners: plasma-runner-[name].desktop
- ScriptEngines: plasma-scriptengine-[type]-[name].desktop where type may be one or more of Applet, DataEngine and/or Runner.