I started learning how to write Cinnamon extensions. Well, I try to ... While I managed to write a first simple desklet, I still didn't find a really good and up to date documentation and introduction.
I have the following questions and would be very glad to get some hints:
What is the best / suggested development workflow?
For now, I do:
copy the changed files from my project directory to .local/share/cinnamon/uuid,
open Melange / Looking Glass,
search there for the extension and reload it via right click
switch to the Log tab and check for errors
Compared to vue.js development with automatic hot-reload of changes in the browser, this seems a bit ... well ... time-consuming.
Where do I find an introduction to the available widgets and widget libraries?
I understood that there is Gtk and St and both have JS / GJS / CJS bindings.
The Gnome Dev Docu doesn't mention St. And I read in another answer here that it seems that shell extensions doesn't use Gtk, but rather St instead (and not in addition?).
I didn't find any documentation for CJS at all, but as far as I understood so far, it seems to be quite similar to GJS. Seems that the way desklets and applets are defined is different?
But now, I still would enjoy to have a (at least brief) introduction which widgets are available. While in Gtk there seems to be a whole set of different list-like widgets, I didn't find any list widget in St. And it seems that I can't use Gtk widgets as children of St widgets ...? This St documentation lacks any overview of available widgets and classes and what they can be used for.
Documentation about events
I found that there is the St.Entry widget that can be used for single-line text input. I found somewhere that I can bind functions to key press key release events like this:
this.input.connect('key-release-event', (widget, event) => {
const input = widget.get_text();
// ...
return true; // event has been handled
});
I didn't managed to get some information for the event.
When printing with JSON.stringify(event) It shows an empty object.
This Gtk documentation looks like there should be fields such as keyval and state, but these are undefined.
This is really kind of frustrating when it takes ages for every very small step to understand ... so, I would really appreciate any hints and suggestions!
Firstly I should note I have no idea what's been happening in CJS since it was split from GJS. Things have been moving pretty fast in GJS, so you may have to ask for help from the Cinnamon community if CJS hasn't been tracking upstream GJS.
The first place you should start is gjs.guide, which is the actively maintained portal for GJS and GNOME Shell extension documentation. There is also an Architecture page which briefly describes the relation of GNOME Shell extensions to the GNOME platform.
Workflow
There is a tiny snippet about how to test an extension by either restarting GNOME Shell or running a nested Shell, but it will need to be expanded at some point:
To restart GNOME Shell in X11, pressing Alt+F2 to open the Run Dialog and enter restart (or just r).
To run new extensions on Wayland you can run a nested gnome-shell using dbus-run-session -- gnome-shell --nested --wayland.
But again, I don't if the above will work with Cinnamon/CJS.
Overview of Widgets
Bindings for GJS are generated from introspection files, which are also used to generate the API documentation. In other words, our "GJS" version of the API documentation will only include material parsed from the C source. In the case of libraries like GLib, Gio, Gtk and so on, you can reference the C documentation for any other material and it should still make sense.
In the case of Clutter, I like to think of it as Gtk if the only widget was GtkWidget, with all of it's machinery. When it comes to St, almost every class is a direct analog of a Gtk widget, such as GtkButton and StButton. If you don't know what a class is for, chances are you can just glance at the Gtk documentation and you'll realize "Oh, StIcon is basically just GtkImage".
Mutter, on the other hand, there is no such high-level tutorials or overviews. It's best just to join Matrix or discourse.gnome.org and ask the community of extension developers and shell developers.
Events
With regard to Clutter.KeyEvent, I had actually forgotten how this situation was a little tricky and non-obvious. Put simply: "events" in this context are sort of polymorphic (I believe they're unions in C) which is why the generated API in GJS is a bit confusing. If you see Clutter.Event.get_key_symbol() and then browse around that page I think it will become clear and you should find all the accessors you need.
Here is the list of key symbol constants and the list of key symbol constans as C definitions in the source might be easier for searching.
I just found https://projects.linuxmint.com/reference/git/cinnamon-tutorials/ that also includes the Cinnamon-specific parts (but haven't looked into the details yet, I'll update :-))
I added some links to the referenced manuals below. For St I did not find an online version yet. But: you can install some dev documentation offline via sudo apt install cinnamon-doc. This adds the Devhelp program in the Programming category of your menu and it has reference manuals for Cinnamon components and for libraries it uses.
Overview
The documentation of Cinnamon is separated into 4 different parts (5
if you count muffin). What you are currently reading is the tutorials,
which includes the general top-level overviews and tutorials you will
need for Cinnamon. This is named “Cinnamon Tutorials”.
The second part is the Javascript reference, which describes the
Javascript part of Cinnamon. This is named the “Cinnamon Javascript
Reference Manual”. This is a technical reference for the individual
functions and objects available in Cinnamon. Note that this
documentation is aimed at both applet/extension developers and
Cinnamon developers themselves. So depending on who you are, some of
the information might be entirely irrelevant.
The third part of the documentation is for the C part of Cinnamon,
which is simply referred to as the “Cinnamon Reference Manual”.
The last part is the documentation for Shell toolkit, or St. This is
the graphical toolkit used to draw widgets on the screen (similar to
Gtk).
The modules covered by the Javascript documentation are those imported
via imports.ui.* and imports.misc.*. The global object is documented
in the C part of Cinnamon, as well as things accessed through
imports.gi.Cinnamon. Things accessed through imports.gi.St are,
unsurprisingly, documented in the St part.
imports.gi.Meta refers to Muffin, while others (eg. imports.gi.Gio)
are third-party (usually GNOME) libraries that are documented
elsewhere.
Accessing the documentation
There are two ways of accessing this documentation, one of which is
what you are currently using. The first method is accessing it online,
which will be available at http://linuxmint.github.io.
The second method is to access it locally. Install the program devhelp
and the cinnamon-doc package (might be named differently in different
distros or included in the cinnamon package itself). Then run the
program devhelp to access all documentations you have installed in
your system (not limited to Cinnamon).
And also worth a look might be the Linux Mint Developer Guide
The CJS repo in GitHub includes also some docs and examples (that are GJS apps in fact, but nevertheless a source of inspiration).
Related
I am very new to GNOME extension development, and I am having a hard time working with it, due to a profound lack of documentation (or maybe my Internet is clandestinely censored) of the API. I started by modifying an existing extension, so that it is easier to make my way around it.
The issue is, I can obtain the active window using global.display.focus_window, and also a list of monitors connected to the computer using Main.layoutManager.monitors. Now, what I would like to do, is find out which monitor the obtained window is sitting on (so I can move the top panel to that monitor, as it probably means I am working on that monitor at the moment). I tried various things, like .screen, .monitor etc., but with no success. I have no IntelliSense completion on this, and I am trying to guess what the members could be, as I cannot seem to find any docs on it.
I appreciate the fact that GNOME is way more customizable than what I used before (Unity, which provided no customization at all), but I don't know how to work with it and resources are scarce. I tried looking into the source code, but I am not familiar with how it is organized and I could not find the relevant portion of code where the members I need, if they exist, are declared.
I am coding the .js files, so I need some JavaScript code, I guess.
Thank you very much.
While most of the user-visible parts of Gnome Shell are written in JavaScript, these are often just bindings for the underlying C libraries. If you're working with Windows, Monitors and Screens then you're going to want to reference the Mutter documentation and probably the Shell documentation as well:
Mutter: https://gjs-docs.gnome.org/#q=meta
Shell: https://gjs-docs.gnome.org/shell01/
St (Shell Toolkit): https://gjs-docs.gnome.org/st10/
There is a property on the global object called screen (so global.screen) which is no doubt a MetaScreen which has a function get_n_monitors(), as well as get_primary_monitor(), get_current_monitor() and others. MetaWindow, on the other hand, contains a function called get_monitor() which returns an integer. I gather that monitors are referred to by integer number, which is passed to various functions of MetaScreen and MetaWindow, since there doesn't seem to be an object for that in the Mutter documentation.
Most of the related JavaScript for what you want to do seems to be in layout.js, which probably has better examples of how Mutter is used in Gnome Shell than I can give you. It also includes a Monitor class, which seems to just be a JS wrapper around the monitor index. This class is used in the LayoutManager class (which is the definition of the instance Main.layoutManager).
A note about documentation
Originally, the rationale for not having "proper" gnome-shell documentation was that the (internal JavaScript) API was pretty unstable. The deal was, you don't get a stable API but you get to read the source in the same language you're going to write it in. In some ways this makes sense, given that you can modify the prototype of live objects and monkey-patch at whim.
The API has settled down a lot, but no one has really stepped up to write a script to auto-document it, yet. My best advice would be to bookmark the Mutter, Shell and St documentation and use Github or GitLab's search to make things easier.
There is however documentation for the Gnome API as well some of the built-in modules that are worth a skim:
Gnome API: https://gjs-docs.gnome.org/
Modules: https://gitlab.gnome.org/GNOME/gjs/blob/master/doc/Modules.md
General GObject usage in GJS: https://gitlab.gnome.org/GNOME/gjs/blob/master/doc/Mapping.md
Is there a Node.js module that handles AES-CMAC (RFC 4493)?
I've been searching around NPM, Google, and the like, but haven't found one. Somebody within my company built one that wraps Crypto++ as a C++ addon for Node.js, but unfortunately it doesn't build on Windows (depends on make). Just looking for possible alternatives.
This is similar to this other question, but I'm hoping for a Node.js specific implementation instead of a plain JavaScript one. Ideally something that makes use of Node's crypto library or a C/C++ addon for performance.
It seems like it wouldn't be too hard to build one, but I'd like to avoid doing so if there is already one out there.
Since I couldn't find anything, I ended up creating my own module: node-aes-cmac
As I learned more, I discovered that RFC 4493 is specific for 128 bit keys (AES128). But it references the NIST Special Publication 800-38B which gave the additional information I needed to support 192 and 256 bit keys as well.
Here is the situation: A complex web app is not working, and it is possible to produce undesired behavior consistently. The cause of the problem is not known.
Proposal: Trace the execution paths of all javascript code. Essentially, produce two monstrous logs which can then be fed into a diff algorithm to determine where the behavior related to the bug begins to diverge (as the cause is not apparent from application behavior, and both comprehending and obtaining a copy of the actual JS code being run is difficult, due to the many pages that must be switched to and copied out from the web inspector. Making it difficult is the fact that all pages are dynamically spliced together with Perl code, where significant portions of JS code exist only as (dynamic...) Perl strings).
The Web Inspector in Chrome does not have an option that I know about for logging an execution trace. Basically what I would like is a log of every line of JS that is executed, in the order that they are executed. I don't see this as being a difficult thing to obtain given that the JS VM is single-threaded. The problem is simply that the existing user-facing tools are not designed for quite this much hardcore debugging. If we look at the Profiler in the Dev Tools, it's clearly capable of the kind of instrumentation that I need, but it is fundamentally designed to do profiling instead of tracing.
How can I get started with this? Is there some way I can build Chrome from source, where I can
switch off JIT in V8?
log every single javascript expression evaluated by V8 to a file
I have zero experience with the development side of Chrome. So e.g. links to dev-builds/branches/versions/distros of Chrome/Chromium/Canary (what's the difference?) are welcome.
At this point it appears that instrumenting the browser with powerful js tracing is still likely to be easier than redesigning the buggy app. The architecture of the page is a disaster, but the functionality is complex, and it almost fully works. I just have to find the one missing piece.
Alternatively, if tools of this sort already exist, what are some other keywords I can search for them with? "Code Tracing" is pretty much the only thing I can come up with.
I tested dynaTrace, which was a happy coincidence as our app supports IE (indeed Chrome support just came out of beta), but this does not produce a text dump, it basically produces a massive Win32 UI expando-tree, which is impossible to diff. This makes me really sad because I know how much more difficult it was to make the representation of the trace show up that way, and yet it turns out being almost utterly useless. Who's going to scroll up and down that tree view and see anything really useful in it, in anything other than a toy example of a web app?
If you are developing a big web app, it is always good to follow a test driven strategy for the coding part of it. Using just a few tips allows you to make a simple unit testing script (using QUnit) to test pretty much all aspects of your app. Here are some potential errors and some ways of solving them.
Make yourself handlers to register long living Objects and a handler to close them the safe way. If the safe way does not succeed then it is the management of the Object itself failing. One example would be Backbone zombie views. Either the view has bad code in the close section, the parent close is not hooked or an infinite loop happened. Testing all view events is also good, although tedious.
By putting all the code for data fetching inside a certain module (I often use a bunch of Backbone.Model objects for each table/document in my DB) and handlers for each using a reqres pattern, you can test them 1 by 1 to see if they all fetch and save correctly.
If complex computation is needed, abstract it in a function or module so that it can be easily tested with known data.
If your app uses data binding, a good policy is to have a JSON schema for all data to be tested against your views containing your bindings. Check against the schema all the data required. This is applied to your Backbone.Model also.
Using a good IDE also helps. PyCharm (if you use Python for backend) or WebStorm are extremely good for testing and developing JavaScript/CoffeeScript. You can breakpoint and study your code at specific locations, inside your browser! Also it runs your code for auto-completion and you can see some of the errors that way.
I just cannot encourage enough the use of modules in your code. Although there is no JavaScript official way of doing it (next ECMAScript draft has it), you can still use good libraries for it. Good ones are: RequireJS, CommonJS or Marionette.Module (if you use Marionette as your framework). I think Ember/AngularJS also offers this kind of functionality but I did not work with them personally so I am not sure.
This might not give you an immediate solution to your problem and I don't think (IMO) there is an easy one either. My focus was to show you ways to develop so that errors can be easily spotted and countered, and all of it (depending on your Unit Testing) during development phase. Errors will always happen, as much as our programmer ego wants us to believe the contrary. Hope I helped :)
I would suggest a divide and conquer strategy, first via logging, and second via code. Wrap suspect methods of the code with console logging in and out events and when the bug occurs hopefully it is occurring between or after some event. If event logging will not shed light, bring parts of the code into a new page/app. Divide and conquer will find when the error starts occurring.
So it seems you're in the realm of weird already, so I'm thinking of a weird solution. I know nothing about the backend of chrome myself so we're in the same boat, but if you're feeling bold here's an idea. Maybe you could find/replace every newline in your javascript files with a piece of code that logs either to a global string or to the console a) what file you're in, b) the contents of "this" or something useful to you, and maybe even c) the time. This would at least get you started. Make sure it's wrapped in something distinct so you can just as easily remove it.
I need to choose a documentation generator (similar to jdoc in java or rdoc in ruby) for my javascript project that (built with jquery, underscore and backbone)
Candidates:
jsdoc toolkit
pdoc
natural docs
docco
YUI doc
doctool http://jquery.bassistance.de/docTool/docTool.html
other ?
Requirements
should work with jquery, underscore and backbone. that means object-literal methods etc
I really like pdoc but its too centered around prototype, poorly documented, and I don't want to make extra files (sections?) to make it work (not sure about this)
docco is nice but I want structured output (as in menu + class/func structure like jdoc)
must be command line/makefile compatible (not web pastie)
Tips, tricks, tutorials, success stories, advice greatly welcomed.
Why Doesn't jQuery use JSDoc?
I would rate jsduck from Sencha on top. I have used it on many projects. Simple to use
https://github.com/senchalabs/jsduck
A single command will generate docs like this http://docs.sencha.com/touch/2-0/
You could also look at Dox by TJ Holowaychuk; it's a fork of Docco, but adds some jsDoc syntax support. I personally find that jQuery code often lends itself to looser style of inline documentation like Docco, but I'm currently in the same situation of trying to decide what doc system to use.
I am going through the same exercise at the moment, and from what I've seen YUI Doc is the best. I love the fact that you can run it in "server" mode and view the documentation as you write it. Much better than having to execute a build each time you change the documentation. Also, the documentation that is generated is very easy to read and very well organized.
This is new so it may not fit your output requirements, but you might find njsdoc interesting. Unlike most JS documenters it tries to build documentation by executing the code and investigating the stack rather than just parsing the files for annotations.
https://bitbucket.org/nexj/njsdoc
There is DocumentJS*
*I haven't used it and I am not sure how well it will integrate with Backbone.
Question
I'm wondering how different ExtendScript is from JavaScript? Could I theoretically hire a web developer who has JavaScript savvy to develop it without demanding an excessive amount of learning on their part?
Overview
I'm working on a media database (or a so-called "multimedia library") project and it is based on XMP (the eXtensible Metadata Platform). The logical tool for administering the metadata and keywording seems to be Adobe Bridge, however I need to contract out the development of a couple of scripts to add a few key functions to Bridge, mainly for interfacing with a server-stored controlled keyword vocabulary.
Upper management, in their infinite wisdom, has decided that putting a software alpha/beta tester and Adobe heavy-lifter [me] in charge of developing the project discovery is the best way to go about this. Whilst I know what I need done, I'm unsure who can actually do it.
Regrettably, my programming knowledge is limited to C++, XML, Apple Script and web languages (unfortunately not including JavaScript), so I'm way out in the weeds when it comes to questions about JavaScript.
Bridge Developer Center
Adobe has a handy SDK out there on the subject, but I can't really make much sense of the overall picture. Much of the Adobe user-to-user forum content is old or unrelated.
Project description
I need a menu added to the menu bar with three options. The three options would all use "Clear and Import" function possible in Bridge's Keywords panel to import 1 of 3 different tab-delimited text files from the database server using either the FTP or HTTP object.
The reading I've done in the Bridge SDK and JavaScript guide suggests that menu items can be added as I've shown in the image below for clarity. Additionally, I've managed to get a very rough version of the "Clear and Import" method to work as a startup script, however I'd like to be able to call them on the fly by clicking on the appropriate menu entry.
For a larger view of the image, click here
ExtendScript is very close to regular JavaScript. They've made a few extensions (e.g., operator overloading) but overall the two are very similar. Adobe products include an IDE called the "ExtendScript Toolkit" (ESTK) that provides a nice environment for writing scripts with an interactive debugger.
You can create new menu items in Bridge by creating instances of MenuElement. Set the onSelect property of the MenuElement object you create to be the function you want the menu item to perform when you select it. The Bridge CS4 JavaScript Reference guide has all the details.
If it's anything like the scripting used for the old Flash IDE, then I think it's just straight javascript/ECMAScript. The only real difference is the APIs you have avaialble. I expect anyone who's good with javascript would be able to pick it up fairly quickly.