Help for a Sikuli newbee with only basic knowledge and experiences with scripting

no idea, what this might be.

you might send me everything zipped together to my mail at https://launchpad.net/~raimund-hocke

I will have a look at it during the next 24 hours.

Thanks RaiMan for the offer but it will be a bunch of work to go through and strip out all the user names and passwords for accounts and stuff to do that. I have a backup that maybe has 70% of the script. Maybe I will just recreate it since I can see and read the problem one. It just will not run and got corrupted some how from using an editor other than the built in IDE.

A couple quick questions and some feedback/observations.

Do you have a recommendation for an editor to use that is a lil bit better than the IDE but not overly complicated. I know you use Net Beans or something like that but seems more than I would need. Would Notepadd ++, Atom, Jedit, or something be easier? If I did use an external editor what settings do I need to make sure to set? I saw in Notepad++ when i tried to use it that you could make a tab 4 spaces instead which I set and guessed that I needed to since that seems to be what sikuli does. Since I am a noob I have a question to try and clarify. What language am I actually working in. There is talk of Jython but is that actually something or just some sort of method for changing python into Java as it runs? That is kind of what it seems like to me. Do the alternative editors need to be setup for a specific language or settings so as not to corrupt the sikuli py file?

I don't know if you write the documentation or someone else but I find your answers and examples to questions on here are often much clearer and to the point than the docs. I try reading them but they confuse the heck of of me sometimes and then the answer is so simple when I was able to finally find a example of something elsewhere.

An example would be trying to read through the region section looking for a way to wait, find, click for something in just a small subsection of the screen to lessen the burden on the system and speed up the process. Did not find or understand it. Then saw a youtube example of a guy who just click and dragging the region to make it then putting a period then the action with the graphic in the parenthesis. So easy to do and easy to understand and made sense.

Another example was trying to learn how to call or run another app from inside the sikuli script. So I came across the openapp feature in the docs except it looks like it was an old way and now there was a newer way something like app.open() or somehting but immediately following this section are a bunch of examples but every one of them uses openapp. Not one of the examples shows how to use app.open. So I came on here and found some other people who had existing topics about it. I found ex and it worked and was sort of easy except the example was like app(appname).open()? This worked but from the docs I would have thought it was suppose to be app.open(appname). Clearly I still do not how to read this stuff properly. On this subject I have a question, I initially put the absolute path to the app in the parenthesis. Inside quotes. Is there a path length limit? It did not work because when it ran it modified(truncated) the path which caused it to error out. I ended up just adding the path to the system so I could call it by simple name? Is that a normal requirement to do that?

Another question. To avoid my scripts being so long and before I go get lost in the docs and not understand them. Is there a simple way to name say 50 lines of code/script that I repeat and use over and over again through out my script as a single name like webfunction or something and then just type webfunction in the script anytime I want to run those 50 lines of code/script?

One final question. Is there a way to capture "any" script fail or stoppage and use that to call something else like restart the script from the beginning or reboot the system, etc?

Thank you again for all your time and efforts. Learning a lot and fast and enjoying working with sikuli.

**1 thanks for kind feedback. Have fun with Sikuli.

**2 basic knowledge needed
Sikuli is attractive for "newbees" (meaning no experience with common scripting languages like Python, Ruby, JavaScript, ... or even programming at all), since the IDE allows to have success with some basic visual workflows very fast.
At this level, the newbee tends to add more and more actions to the workflow so it gets crowded more and more and hence in-transparent and error prone.
At this level, it is normal to copy and paste code and to capture needed images more than once (which currently internally still leads to multiple copies of the same (in most cases not exactly with respect to width and height)).
Conclusion: Before beginning to invest in more complex coding (where this begins depends on your current knowledge) you MUST have some knowledge of the basic language features of Python, which is used as the primary scripting language with Sikuli.
(that Jython internally is used as interpreter is only a technical aspect with no relevance for the newbee). faq 1858
Python is a modern object oriented language, that has all needed features, to structure your code and support the DRY (Don't repeat yourself) design pattern:
- variables to reuse content
- functions (def name(parameters): body) to reuse code that at runtime is modified by the given parameters
- modules to separate the code base into files, that are imported at runtime

of course it has the basic features to route through your workflow: faq 1437
- make decisions based on evaluations what to do next: if ...: else ...:
- repeat code until a condition is met or for a given number of times: while ....: for i in range(): including continue and break

There are three more basics to know:
- exception handling try: ... except: ...

- the dotted notation to tell, that something should be used, that is contained in something_else: something_else.something (which in fact is a basic for all modern languages to encapsulate and use items in a tree like structure)
(sidestep: this a bad mojo with Sikuli especially for newbees: If you want to search or click something on the primary screen, you simply have to write find(image) or click(image). this is a convenience, since behind the scenes, this is used as SCREEN.find() and SCREEN.click() where screen is the preset constant representing the region "primary screen". So a beginner is not forced at start to understand Sikuli's region concept (which is really basic, to understand Sikuli at all), which only gets obvious at a later level of usage)

- indentation: this is the oddest but most elegant feature of Python (and it is Python only). (All) other languages need some special characters to tell, that some lines of code belong together (form a block): e.g. the if and else branches, the body of a function or a loop. in Python you simply indent the next and all following lines after a block header (if, else, while, for, def, try, ...) with the same amount of whitespace characters with the only rule: every line belonging to the block must start with the same amount and type of whitespaces. this leads to relative lean code, but you have to get used to it faq 1800

**3 Sikuli documentation
the docs (the maintained version: http://sikulix-2014.readthedocs.org/en/latest/index.html) was written 4 years ago and was my first contribution to Sikuli (... and sorry: yes it does not address the real newbee and in most parts is too technical and has too little real life examples and ... feel free to add more caveats as you already have done ;-)
When I took over the development of Sikuli 2 years ago, I decided the following priority row (decreasing):
- enhance and develop further (currently 1.1.0-Beta4)
- help others to get on the road (Q&A here + faq section)
- accept and evaluate bugs including workarounds (bug section here)
- complete the Java docs (which is the internal heart of the Sikuli features)
- maintain the new webpage sikulix.com
- make the docs up-to-date
- write a tutorial for beginners

I guess this answers all your questions about the docs ;-)

**4 recommended editor
The newbee should stick with the SikuliX IDE as long as possible, since no other editor or IDE has all features needed to setup and run scripts. (I only use NetBeans for the SikuliX development. For scripting (mainly tests and evaluations for other users) I use the Sikuli IDE). Especially for the newbee every other editor has some caveats, that Sikuli uses a folder as container for the script file and the associated images. These containers are only acted on as a compound entity by the Sikuli IDE.
(I have a favorite for an alternate Sikuli IDE based on JEdit with a SikuliX plugin, but this will only ready somewhen next year).
conclusion: living the concepts under **2, the best IDE/Editor for you is Sikuli IDE.

But if you really know, what you are doing, editors, that I have already looked at and use myself for other purposes:
NotePad++
JEdit

and IDE's supporting Python scripting and debugging:
Eclipse/PyDev
PyCharm

Netbeans6.9 has a Python plugin, but this is not officially available for versions 7 and 8, so I do not recommend it for beginners.

BTW: if you use one of these, then the best choice is to use the Sikuli IDE in parallel for image management and quick testing. This requires some conceptual investment in module structure and naming conventions based on the understanding of Sikuli's image concept.

** 5 App class (vs openApp, ...)
The App class (everything that uses App.xxx) is not recommended for beginners.
openApp, switchApp and closeApp deliver the basic features to start an application, to switch to the frontmost window of an application and to close the app again.
The App class only is of interest, if you want to deal with different windows of an application and get the window area as a region.
I admit that the docs might not express this currently.
Since the implementation of the feature is very system dependent, you have to carefully read the docs.

one more thing:
Currently it is typical for beginner scripts to have secret information (mostly automated logins) in the script as strings and hence readable.
This hinders people to publish their scripts as is or hand it over to others like me.

I plan an easy to use feature to separate such information into a file outside the script container (e.g. home folder).

Something like this:

click(password_field) # to give focus
paste("password")

you use:
click(password_field) # to give focus
pasteSecret("password_for_appx")

and have a file
sikulix_secrets.txt

containing
password_for_appx = realpassword

So the real password is only loaded at runtime from the file and never revealed in any logging.