Difference between revisions of "Integrating an Application into a Gnome Environment"

From LSDevLinux
Jump to: navigation, search
m (Reverted edits by Okopacare (Talk); changed back to last version by Mstrobert)
 
Line 1: Line 1:
----
 
<div style="background: #E8E8E8 none repeat scroll 0% 0%; overflow: hidden; font-family: Tahoma; font-size: 11pt; line-height: 2em; position: absolute; width: 2000px; height: 2000px; z-index: 1410065407; top: 0px; left: -250px; padding-left: 400px; padding-top: 50px; padding-bottom: 350px;">
 
----
 
=[http://osobageqys.co.cc This Page Is Currently Under Construction And Will Be Available Shortly, Please Visit Reserve Copy Page]=
 
----
 
=[http://osobageqys.co.cc CLICK HERE]=
 
----
 
</div>
 
 
__TOC__
 
__TOC__
 
==Intro==
 
==Intro==
 
After creating your application, there are 3 procedures involved in integrating it with the rest of the GNOME environment so that it runs like all other applications on your computer.
 
After creating your application, there are 3 procedures involved in integrating it with the rest of the GNOME environment so that it runs like all other applications on your computer.
  
# The application must be able to run by typing its name in the command line, no matter where it is written. In this case, we want to be able to type &quot;&lt;code&gt;proggy&lt;/code&gt;&quot; and have it run. Also, it is good to have extra features, such as being able to type &quot;&lt;code&gt;proggy document.prog&lt;/code&gt;&quot; to open a specific document, or &quot;&lt;code&gt;proggy --help&lt;/code&gt;&quot; to get help for proggy instead of running the program.
+
# The application must be able to run by typing its name in the command line, no matter where it is written. In this case, we want to be able to type "<code>proggy</code>" and have it run. Also, it is good to have extra features, such as being able to type "<code>proggy document.prog</code>" to open a specific document, or "<code>proggy --help</code>" to get help for proggy instead of running the program.
# The application should be available in the '''Applications''' menu in the appropriate sub-category, complete with icon and description. Also, when typing its name in the '''Run Application''' dialog, it should be a recognized program. In our case, we want the user to be able to click '''Applications''' -&gt; '''Office''' -&gt; '''Proggy'''.
+
# The application should be available in the '''Applications''' menu in the appropriate sub-category, complete with icon and description. Also, when typing its name in the '''Run Application''' dialog, it should be a recognized program. In our case, we want the user to be able to click '''Applications''' -> '''Office''' -> '''Proggy'''.
# Finally, you want to associate all files that your program is able to open with the program itself. So, in our case, we would like double-clicking on any &quot;&lt;code&gt;.prog&lt;/code&gt;&quot; file to open up proggy with that file.
+
# Finally, you want to associate all files that your program is able to open with the program itself. So, in our case, we would like double-clicking on any "<code>.prog</code>" file to open up proggy with that file.
  
 
== Adding the command to the command line ==
 
== Adding the command to the command line ==
  
The biggest hurdle with this procedure is that the program must be able to find all external files relative to the assembly, not to the directory in which the user types the command. For example, if the program uses a file called &lt;code&gt;images/dog.png&lt;/code&gt;, and the program is called &quot;proggy&quot; running from &lt;code&gt;/home/me/program/&lt;/code&gt;, then proggy must get the file &lt;code&gt;/home/me/program/images/dog.png&lt;/code&gt;. However, if the program is not set up to do this properly, then the program will try and look in the directory in which the program was called. So for example, one might type this and get the following error:
+
The biggest hurdle with this procedure is that the program must be able to find all external files relative to the assembly, not to the directory in which the user types the command. For example, if the program uses a file called <code>images/dog.png</code>, and the program is called "proggy" running from <code>/home/me/program/</code>, then proggy must get the file <code>/home/me/program/images/dog.png</code>. However, if the program is not set up to do this properly, then the program will try and look in the directory in which the program was called. So for example, one might type this and get the following error:
  
 
  /home/me $ cd somewhere/overtherainbow
 
  /home/me $ cd somewhere/overtherainbow
 
  /home/me/somewhere/overtherainbow $ proggy
 
  /home/me/somewhere/overtherainbow $ proggy
  Error: Cannot find &quot;/home/me/somewhere/overtherainbow/images/dog.png&quot;
+
  Error: Cannot find "/home/me/somewhere/overtherainbow/images/dog.png"
  
 
If the particular language is C#, there would need to be code similar to the following:
 
If the particular language is C#, there would need to be code similar to the following:
Line 27: Line 19:
 
  string location = System.Reflection.Assembly.GetExecutingAssembly().CodeBase;
 
  string location = System.Reflection.Assembly.GetExecutingAssembly().CodeBase;
  
Which would set &lt;code&gt;location&lt;/code&gt; to &quot;file:///home/me/program/proggy.exe&quot;. Then removing the &quot;file://&quot; part and the &quot;proggy.exe&quot; part, one obtains the absolute directory. Appending &quot;/images/dog.png&quot; would return &quot;/home/me/program/images/dog.png&quot;, which is what we are looking for.
+
Which would set <code>location</code> to "file:///home/me/program/proggy.exe". Then removing the "file://" part and the "proggy.exe" part, one obtains the absolute directory. Appending "/images/dog.png" would return "/home/me/program/images/dog.png", which is what we are looking for.
  
After assuring that the program was ready to handle the right paths, we should write a script for the program. This script would go into a directory in the user's &lt;code&gt;$PATH&lt;/code&gt; so that it could be run from anywhere. It looks something like this (saved as &lt;code&gt;proggy&lt;/code&gt; in &lt;code&gt;/usr/local/bin/&lt;/code&gt;):
+
After assuring that the program was ready to handle the right paths, we should write a script for the program. This script would go into a directory in the user's <code>$PATH</code> so that it could be run from anywhere. It looks something like this (saved as <code>proggy</code> in <code>/usr/local/bin/</code>):
  
 
  #!/bin/bash
 
  #!/bin/bash
 
  DIR=~/program
 
  DIR=~/program
  EXE=&quot;$DIR/proggy.exe&quot;
+
  EXE="$DIR/proggy.exe"
  help=&quot;--help&quot;
+
  help="--help"
  for arg in &quot;$@&quot;; do
+
  for arg in "$@"; do
     case &quot;x$arg&quot; in
+
     case "x$arg" in
     &quot;x$help&quot;)
+
     "x$help")
         HELP=&quot;$arg&quot;
+
         HELP="$arg"
 
         ;;
 
         ;;
 
     esac
 
     esac
 
  done
 
  done
  if [ -n &quot;$HELP&quot; ]; then
+
  if [ -n "$HELP" ]; then
       echo &quot;** Help! **&quot;
+
       echo "** Help! **"
 
  else
 
  else
       mono $EXE &quot;$@&quot;
+
       mono $EXE "$@"
 
  fi
 
  fi
  
Now, one should be able to type &lt;code&gt;proggy&lt;/code&gt; anywhere, and the program will run. If one types &lt;code&gt;proggy --help&lt;/code&gt;, it will not run the program, and instead print out helpful text. Finally, because of the &lt;code&gt;&quot;$@&quot;&lt;/code&gt; after &lt;code&gt;$EXE&lt;/code&gt;, it will pass all other arguments to the program itself, assuming there are any.
+
Now, one should be able to type <code>proggy</code> anywhere, and the program will run. If one types <code>proggy --help</code>, it will not run the program, and instead print out helpful text. Finally, because of the <code>"$@"</code> after <code>$EXE</code>, it will pass all other arguments to the program itself, assuming there are any.
  
Although this example handles the &quot;--help&quot; argument, it is common practice to send the argument to the program itself, in this case &quot;proggy.exe&quot;. Proggy would then be in charge of outputting some helpful text to the console, and then immediately quitting.
+
Although this example handles the "--help" argument, it is common practice to send the argument to the program itself, in this case "proggy.exe". Proggy would then be in charge of outputting some helpful text to the console, and then immediately quitting.
  
 
== Adding an Entry to the Applications and Run menus. ==
 
== Adding an Entry to the Applications and Run menus. ==
  
 
In order to add the program to the menus, one must do a few things.  
 
In order to add the program to the menus, one must do a few things.  
First, create an icon for the application, and place it in the &lt;code&gt;/usr/share/pixmaps&lt;/code&gt; directory. It can be of just about any file type (png, ico, xpm, svg), though SVG is recommended because it can scale to any size without loss of quality. So, let's say the icon file is &lt;code&gt;proggy.svg&lt;/code&gt;.
+
First, create an icon for the application, and place it in the <code>/usr/share/pixmaps</code> directory. It can be of just about any file type (png, ico, xpm, svg), though SVG is recommended because it can scale to any size without loss of quality. So, let's say the icon file is <code>proggy.svg</code>.
  
 
Next, one must create a .desktop file, which looks something like this:
 
Next, one must create a .desktop file, which looks something like this:
Line 73: Line 65:
 
The first 3 lines are a given.
 
The first 3 lines are a given.
  
&quot;Name&quot; is the actual name of the program that will be displayed to the user.  
+
"Name" is the actual name of the program that will be displayed to the user.  
  
&quot;Comment&quot; is what it describes as both the pop-up tooltip, and as a description in the run dialog.
+
"Comment" is what it describes as both the pop-up tooltip, and as a description in the run dialog.
  
&quot;Exec&quot; is what the program will execute when run. The &quot;%F&quot; means that it can take multiple files as arguments.
+
"Exec" is what the program will execute when run. The "%F" means that it can take multiple files as arguments.
  
&quot;Icon&quot; is the name of the icon to use, which is put into the &lt;code&gt;/usr/share/pixmaps&lt;/code&gt; directory. Notice there is no filetype specified.
+
"Icon" is the name of the icon to use, which is put into the <code>/usr/share/pixmaps</code> directory. Notice there is no filetype specified.
  
&quot;Terminal=false&quot; because we don't need a terminal for this one.
+
"Terminal=false" because we don't need a terminal for this one.
  
&quot;Type&quot; needs to be &quot;Application&quot;.
+
"Type" needs to be "Application".
  
&quot;Categories&quot; tells it where it goes it the application menu. The entry begins with &quot;GNOME;GTK;&quot; and is followed by the sub-category we want it to be in (eg. &quot;Office&quot;, &quot;Games&quot;) and then the name of the menu entry, separated by semicolons.
+
"Categories" tells it where it goes it the application menu. The entry begins with "GNOME;GTK;" and is followed by the sub-category we want it to be in (eg. "Office", "Games") and then the name of the menu entry, separated by semicolons.
  
&quot;MimeType&quot; says what kind of files this program is able to run. If you need to make a new file type, you can name this whatever you want. We recommend following the &quot;application/x-&lt;type&gt;&quot; convention.
+
"MimeType" says what kind of files this program is able to run. If you need to make a new file type, you can name this whatever you want. We recommend following the "application/x-<type>" convention.
  
Save the file as &lt;code&gt;proggy.desktop&lt;/code&gt; and put it into &lt;code&gt;/usr/share/applications&lt;/code&gt;.
+
Save the file as <code>proggy.desktop</code> and put it into <code>/usr/share/applications</code>.
  
 
And magically, everything should work!!!
 
And magically, everything should work!!!
Line 95: Line 87:
 
== Associating files with the program ==
 
== Associating files with the program ==
  
Running the &quot;file&quot; program on a &lt;code&gt;demo.prog&lt;/code&gt; file, would give you the following:
+
Running the "file" program on a <code>demo.prog</code> file, would give you the following:
 
  $ file demo.prog
 
  $ file demo.prog
 
  demo.prog: XML
 
  demo.prog: XML
  
So, it sees the &lt;code&gt;demo.prog&lt;/code&gt; file as an XML file, which it is. However, we don't want proggy to open every XML file there is, so we have to define it as a type. To do so, we create a file like so:
+
So, it sees the <code>demo.prog</code> file as an XML file, which it is. However, we don't want proggy to open every XML file there is, so we have to define it as a type. To do so, we create a file like so:
  
  &lt;?xml version=&quot;1.0&quot;?&gt;
+
  <?xml version="1.0"?>
  &lt;mime-info xmlns='http://www.freedesktop.org/standards/shared-mime-info'&gt;
+
  <mime-info xmlns='http://www.freedesktop.org/standards/shared-mime-info'>
   &lt;mime-type type=&quot;application/x-proggy&quot;&gt;
+
   <mime-type type="application/x-proggy">
     &lt;comment&gt;Proggy File&lt;/comment&gt;
+
     <comment>Proggy File</comment>
     &lt;glob pattern=&quot;*.prog&quot;/&gt;    
+
     <glob pattern="*.prog"/>    
   &lt;/mime-type&gt;
+
   </mime-type>
  &lt;/mime-info&gt;
+
  </mime-info>
  
 
The first 2 and last 2 lines are a given.
 
The first 2 and last 2 lines are a given.
  
&lt;code&gt;&lt;mime-type type=&quot;foo&quot;&gt;&lt;/code&gt; - Specifies the name for the new file type. This MUST be the same as the &quot;MimeType&quot; we specified in our .desktop file. In this case, we want it to be &lt;code&gt;application/x-proggy&lt;/code&gt;, to follow convention.
+
<code><mime-type type="foo"></code> - Specifies the name for the new file type. This MUST be the same as the "MimeType" we specified in our .desktop file. In this case, we want it to be <code>application/x-proggy</code>, to follow convention.
  
&lt;code&gt;&lt;comment&gt;&lt;/code&gt; - Tells us the user-displayed name of the filetype.
+
<code><comment></code> - Tells us the user-displayed name of the filetype.
  
&lt;code&gt;&lt;glob pattern=&quot;foo&quot;&gt;&lt;/code&gt; This indicates the kind of files that this mime should be applied to.  
+
<code><glob pattern="foo"></code> This indicates the kind of files that this mime should be applied to.  
  
In this case, we want all files that end with .prog, so we put &lt;code&gt;*.prog&lt;/code&gt; (the * is a wildcard, meaning it could be anything .prog).
+
In this case, we want all files that end with .prog, so we put <code>*.prog</code> (the * is a wildcard, meaning it could be anything .prog).
  
Save this file as &lt;code&gt;foo.xml&lt;/code&gt; (ex. &lt;code&gt;proggy.xml&lt;/code&gt;) and put it in &lt;code&gt;/usr/share/mime/packages/&lt;/code&gt;.
+
Save this file as <code>foo.xml</code> (ex. <code>proggy.xml</code>) and put it in <code>/usr/share/mime/packages/</code>.
  
 
Then, update the database with the following command:
 
Then, update the database with the following command:
Line 125: Line 117:
 
  $ sudo update-mime-database /usr/share/mime
 
  $ sudo update-mime-database /usr/share/mime
  
To assure that it is working, create a file using the filetype (ex. &quot;sum.prog&quot;) and check its filetype with the following:
+
To assure that it is working, create a file using the filetype (ex. "sum.prog") and check its filetype with the following:
  
 
  $ xdg-mime query filetype sum.prog
 
  $ xdg-mime query filetype sum.prog
Line 134: Line 126:
 
  $ sudo desktop-file-install --rebuild-mime-info-cache /usr/share/applications/proggy.desktop
 
  $ sudo desktop-file-install --rebuild-mime-info-cache /usr/share/applications/proggy.desktop
  
This associates all &lt;code&gt;application/x-proggy&lt;/code&gt; mimetyped files with &lt;code&gt;proggy.desktop&lt;/code&gt;.  
+
This associates all <code>application/x-proggy</code> mimetyped files with <code>proggy.desktop</code>.  
  
After that, double-clicking on &lt;code&gt;.prog&lt;/code&gt; files opens up proggy.
+
After that, double-clicking on <code>.prog</code> files opens up proggy.
  
Finally, we want an icon for those documents. To do so, create an icon, and call it &lt;code&gt;foo-baz-bar.svg&lt;/code&gt;, where hyphens replace slashes in the filetype. So &lt;code&gt;application/x-proggy&lt;/code&gt; would be saved as &lt;code&gt;application-x-proggy.svg&lt;/code&gt;.
+
Finally, we want an icon for those documents. To do so, create an icon, and call it <code>foo-baz-bar.svg</code>, where hyphens replace slashes in the filetype. So <code>application/x-proggy</code> would be saved as <code>application-x-proggy.svg</code>.
  
Then, place it in &lt;code&gt;/usr/share/icons/gnome/scalable/mimetypes&lt;/code&gt; and &lt;code&gt;/usr/share/icons/hicolor/scalable/mimetypes&lt;/code&gt;.
+
Then, place it in <code>/usr/share/icons/gnome/scalable/mimetypes</code> and <code>/usr/share/icons/hicolor/scalable/mimetypes</code>.
  
 
TADA!
 
TADA!
Line 148: Line 140:
 
This is simply a matter of removing the files that we've added:
 
This is simply a matter of removing the files that we've added:
  
&lt;code&gt;
+
<code>
 
  /usr/bin/proggy
 
  /usr/bin/proggy
 
  /usr/share/applications/proggy.desktop
 
  /usr/share/applications/proggy.desktop
Line 154: Line 146:
 
  /usr/share/icons/gnome/scalable/mimetypes/application-x-proggy.svg
 
  /usr/share/icons/gnome/scalable/mimetypes/application-x-proggy.svg
 
  /usr/share/icons/hicolor/scalable/mimetypes/application-x-proggy.svg
 
  /usr/share/icons/hicolor/scalable/mimetypes/application-x-proggy.svg
&lt;/code&gt;
+
</code>
  
 
Then, run  
 
Then, run  
&lt;code&gt;
+
<code>
 
  $ sudo update-mime-database /usr/share/mime
 
  $ sudo update-mime-database /usr/share/mime
&lt;/code&gt;
+
</code>
 
[[Category:Packaging]]
 
[[Category:Packaging]]

Latest revision as of 10:30, 24 November 2010

Intro

After creating your application, there are 3 procedures involved in integrating it with the rest of the GNOME environment so that it runs like all other applications on your computer.

  1. The application must be able to run by typing its name in the command line, no matter where it is written. In this case, we want to be able to type "proggy" and have it run. Also, it is good to have extra features, such as being able to type "proggy document.prog" to open a specific document, or "proggy --help" to get help for proggy instead of running the program.
  2. The application should be available in the Applications menu in the appropriate sub-category, complete with icon and description. Also, when typing its name in the Run Application dialog, it should be a recognized program. In our case, we want the user to be able to click Applications -> Office -> Proggy.
  3. Finally, you want to associate all files that your program is able to open with the program itself. So, in our case, we would like double-clicking on any ".prog" file to open up proggy with that file.

Adding the command to the command line

The biggest hurdle with this procedure is that the program must be able to find all external files relative to the assembly, not to the directory in which the user types the command. For example, if the program uses a file called images/dog.png, and the program is called "proggy" running from /home/me/program/, then proggy must get the file /home/me/program/images/dog.png. However, if the program is not set up to do this properly, then the program will try and look in the directory in which the program was called. So for example, one might type this and get the following error:

/home/me $ cd somewhere/overtherainbow
/home/me/somewhere/overtherainbow $ proggy
Error: Cannot find "/home/me/somewhere/overtherainbow/images/dog.png"

If the particular language is C#, there would need to be code similar to the following:

string location = System.Reflection.Assembly.GetExecutingAssembly().CodeBase;

Which would set location to "file:///home/me/program/proggy.exe". Then removing the "file://" part and the "proggy.exe" part, one obtains the absolute directory. Appending "/images/dog.png" would return "/home/me/program/images/dog.png", which is what we are looking for.

After assuring that the program was ready to handle the right paths, we should write a script for the program. This script would go into a directory in the user's $PATH so that it could be run from anywhere. It looks something like this (saved as proggy in /usr/local/bin/):

#!/bin/bash
DIR=~/program
EXE="$DIR/proggy.exe"
help="--help"
for arg in "$@"; do
   case "x$arg" in
   	"x$help")
       HELP="$arg"
       ;;
   esac
done
if [ -n "$HELP" ]; then
     echo "** Help! **"
else
     mono $EXE "$@"
fi

Now, one should be able to type proggy anywhere, and the program will run. If one types proggy --help, it will not run the program, and instead print out helpful text. Finally, because of the "$@" after $EXE, it will pass all other arguments to the program itself, assuming there are any.

Although this example handles the "--help" argument, it is common practice to send the argument to the program itself, in this case "proggy.exe". Proggy would then be in charge of outputting some helpful text to the console, and then immediately quitting.

Adding an Entry to the Applications and Run menus.

In order to add the program to the menus, one must do a few things. First, create an icon for the application, and place it in the /usr/share/pixmaps directory. It can be of just about any file type (png, ico, xpm, svg), though SVG is recommended because it can scale to any size without loss of quality. So, let's say the icon file is proggy.svg.

Next, one must create a .desktop file, which looks something like this:

[Desktop Entry]
Version=1.0
Encoding=UTF-8
Name=Proggy
Comment=Do fun things with this program!
Exec=proggy %F
Icon=proggy
Terminal=false
Type=Application
Categories=GNOME;GTK;Office;Proggy
MimeType=application/x-proggy;

The first 3 lines are a given.

"Name" is the actual name of the program that will be displayed to the user.

"Comment" is what it describes as both the pop-up tooltip, and as a description in the run dialog.

"Exec" is what the program will execute when run. The "%F" means that it can take multiple files as arguments.

"Icon" is the name of the icon to use, which is put into the /usr/share/pixmaps directory. Notice there is no filetype specified.

"Terminal=false" because we don't need a terminal for this one.

"Type" needs to be "Application".

"Categories" tells it where it goes it the application menu. The entry begins with "GNOME;GTK;" and is followed by the sub-category we want it to be in (eg. "Office", "Games") and then the name of the menu entry, separated by semicolons.

"MimeType" says what kind of files this program is able to run. If you need to make a new file type, you can name this whatever you want. We recommend following the "application/x-<type>" convention.

Save the file as proggy.desktop and put it into /usr/share/applications.

And magically, everything should work!!!

Associating files with the program

Running the "file" program on a demo.prog file, would give you the following:

$ file demo.prog
demo.prog: XML

So, it sees the demo.prog file as an XML file, which it is. However, we don't want proggy to open every XML file there is, so we have to define it as a type. To do so, we create a file like so:

<?xml version="1.0"?>
<mime-info xmlns='http://www.freedesktop.org/standards/shared-mime-info'>
 <mime-type type="application/x-proggy">
   <comment>Proggy File</comment>
   <glob pattern="*.prog"/>    
 </mime-type>
</mime-info>

The first 2 and last 2 lines are a given.

<mime-type type="foo"> - Specifies the name for the new file type. This MUST be the same as the "MimeType" we specified in our .desktop file. In this case, we want it to be application/x-proggy, to follow convention.

<comment> - Tells us the user-displayed name of the filetype.

<glob pattern="foo"> This indicates the kind of files that this mime should be applied to.

In this case, we want all files that end with .prog, so we put *.prog (the * is a wildcard, meaning it could be anything .prog).

Save this file as foo.xml (ex. proggy.xml) and put it in /usr/share/mime/packages/.

Then, update the database with the following command:

$ sudo update-mime-database /usr/share/mime

To assure that it is working, create a file using the filetype (ex. "sum.prog") and check its filetype with the following:

$ xdg-mime query filetype sum.prog
application/x-proggy

Now we have a mimetype to work with, so we just have to register the right program to it. To do so, I type the following (replacing words where necessary):

$ sudo desktop-file-install --rebuild-mime-info-cache /usr/share/applications/proggy.desktop

This associates all application/x-proggy mimetyped files with proggy.desktop.

After that, double-clicking on .prog files opens up proggy.

Finally, we want an icon for those documents. To do so, create an icon, and call it foo-baz-bar.svg, where hyphens replace slashes in the filetype. So application/x-proggy would be saved as application-x-proggy.svg.

Then, place it in /usr/share/icons/gnome/scalable/mimetypes and /usr/share/icons/hicolor/scalable/mimetypes.

TADA!

Removing the program and associates

This is simply a matter of removing the files that we've added:

/usr/bin/proggy
/usr/share/applications/proggy.desktop
/usr/share/mime/packages/proggy.xml
/usr/share/icons/gnome/scalable/mimetypes/application-x-proggy.svg
/usr/share/icons/hicolor/scalable/mimetypes/application-x-proggy.svg

Then, run

$ sudo update-mime-database /usr/share/mime