{ "info": { "author": "Keul", "author_email": "lucafbb@gmail.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 4 - Beta", "Intended Audience :: Developers", "License :: OSI Approved :: GNU General Public License (GPL)", "Operating System :: OS Independent", "Programming Language :: Python :: 2.5", "Topic :: Games/Entertainment", "Topic :: Multimedia :: Graphics", "Topic :: Software Development :: Libraries :: Python Modules", "Topic :: Software Development :: User Interfaces" ], "description": "Introduction\r\n============\r\n\r\nThe scope of this library is to help developers to simply display text inside a `pygame.Rect`__ instance.\r\nAfter obtainer a KTextSurfaceWriter instance, you can use its ''draw'' method to display\r\nthe text over a `pygame.Surface`__.\r\n\r\n__ http://www.pygame.org/docs/ref/rect.html\r\n__ http://www.pygame.org/docs/ref/surface.html\r\n\r\nVisit the `home page of the project`__ for more.\r\n\r\n__ http://keul.it/develop/python/ktextsurfacewriter/\r\n\r\nExamples\r\n========\r\n\r\nHere a fully example of use of this library. Even if I use the Python doctest format, this isn't a\r\npolitically correct test because I wait for user input and no real tests are done on the results.\r\n\r\nMaybe someday I'll fix this!\r\n\r\nHowever the code in this page is a working example. If you know nothing about doctests, only know that you can\r\nrun this code simple accessing at the egg source and type:\r\n\r\n python tests.py\r\n\r\nInit all the pygame stuff\r\n-------------------------\r\n\r\nLets begin loading the KTextSurfaceWrite class\r\n\r\n >>> from ktextsurfacewriter import KTextSurfaceWriter\r\n\r\nNow init the minimum pygame environment we need.\r\n\r\n >>> import pygame\r\n >>> from pygame.locals import *\r\n >>> import pygame.font\r\n >>> pygame.font.init()\r\n >>> screen = pygame.display.set_mode((640,480), 0, 32)\r\n\r\nTo make things more complicated, I'll not draw directly on the screen but I get a Surface where I can draw.\r\n\r\n >>> surface = pygame.Surface( (400,400), flags=SRCALPHA, depth=32 )\r\n >>> surface.fill( (255,255,255,255) )\r\n \r\n\r\nNow we can blit the surface on the screen. We will repeat this procedure several times so its better create out first\r\ndummy function (those functions aren't useful outside this test environment):\r\n\r\n >>> def blitSurface():\r\n ... screen.blit(surface, (50,50) )\r\n ... pygame.display.update()\r\n\r\nSo we can call it for the first time.\r\n\r\n >>> blitSurface()\r\n\r\nThis is a graphical test, so we need to delay the drawing and make possible that user can look at results and then go over.\r\nWe wait for user input before going on. To do this we create a second silly function that we'll call often later.\r\n\r\n >>> def waitForUserAction():\r\n ... while True:\r\n ...\r\n ... for event in pygame.event.get():\r\n ... if event.type == QUIT:\r\n ... import sys\r\n ... sys.exit(0)\r\n ... if event.type==KEYDOWN:\r\n ... return\r\n\r\nOk, lets call it for the first time.\r\n\r\n >>> waitForUserAction()\r\n\r\nSimple text drawing\r\n-------------------\r\n\r\nWe are ready to create our instance of the class. The __init__ method want a pygame.Rect.\r\nThis Rect will be our bound, inside which the text will be keep.\r\n\r\n >>> text_rect = pygame.Rect( (10,10),(350,350) )\r\n >>> text_rect\r\n \r\n \r\nThis mean that the text will be displayed on a surface starting from x,y coordinates (10,10)\r\nfrom the top left corner.\r\nThe text will also not be larger than 350 pixels in height and width.\r\n\r\nNow we will load the text inside the KTextSurfaceWriter, but before this we (obviously) need the instance.\r\n\r\n >>> ktext = KTextSurfaceWriter(text_rect)\r\n\r\nNow the text.\r\n\r\n >>> import example_texts\r\n >>> ktext.text = example_texts.EXAMPLE_TEXT_1\r\n\r\nNow some color for a better display experience\r\n\r\n >>> ktext.color = (0,0,0,255)\r\n >>> ktext.fillcolor = (155,155,155,255)\r\n\r\nWe changed the fillcolor to grey because this way is simpler to see that we drawn a white surface onto a\r\nblack screen, and on this surface we blit the text inside a rectangle shorter that the surface itself.\r\n\r\nOk, stop talking, lets display it!\r\n\r\n >>> ktext.draw(surface)\r\n >>> blitSurface()\r\n >>> waitForUserAction()\r\n\r\nSimple (but longer) text drawing\r\n--------------------------------\r\n\r\nThe text above is very short so we didn't tested all the KTextSurfaceWriter features right now.\r\nLets try with a longer ones...\r\n\r\n >>> ktext.text = example_texts.EXAMPLE_TEXT_2\r\n \r\nNow we can immediatly test this new text.\r\n\r\n >>> ktext.draw(surface)\r\n >>> blitSurface()\r\n >>> waitForUserAction()\r\n\r\nWhat is changed? Even if the EXAMPLE_TEXT_2 string is not splitted on several lines, the displayed text never exit from\r\nthe constrain pygame.Rect instance we used!\r\n\r\nAnd what is the text will be already splitted on several lines?\r\n\r\n >>> ktext.text = example_texts.EXAMPLE_TEXT_3\r\n >>> ktext.draw(surface)\r\n >>> blitSurface()\r\n >>> waitForUserAction()\r\n\r\nObviously the carriage return in the text are kept.\r\nWe can also think about do a little indentation, to make different render for new lines that are wanted (because are\r\ninserted into the text) and other that are generated automatically for a too long text.\r\n\r\n >>> ktext.justify_chars = 3\r\n\r\nIf we draw again now, we get no difference.\r\nFor performance needs the KTextSurfaceWriter.draw method don't evaluate every time the text and the font\r\ngraphical stuff, but memoize the result.\r\nWhen you change the text you also automatically invalidate this cache, but if you didn't change it, you can\r\nalways do it manually.\r\n\r\n >>> ktext.invalidate()\r\n\r\nOk, now you'll see the difference.\r\n\r\n >>> ktext.draw(surface)\r\n >>> blitSurface()\r\n >>> waitForUserAction()\r\n \r\nText too loong for a single line\r\n--------------------------------\r\n\r\nWe want to draw text always inside a rectangle, but this isn't always possible, even if we use a pygame.Rect\r\nbig as the entire surface, is always possible that the text we pass is too long.\r\n\r\nWhat happen in this case?\r\n\r\n >>> ktext.text = example_texts.EXAMPLE_TEXT_4\r\n >>> ktext.draw(surface)\r\n >>> blitSurface()\r\n >>> waitForUserAction()\r\n\r\nThe default behaviour is to cut the word at the maximum lenght possible. This because without saying anything the\r\nKTextSurfaceWriter instance use a criteria called \"cut\".\r\nYou can change this to another value\r\n\r\n >>> ktext.line_length_criteria = \"split\"\r\n\r\nThen if we repeat the test we get a new behaviour.\r\n\r\n >>> ktext.invalidate()\r\n >>> ktext.draw(surface)\r\n >>> blitSurface()\r\n >>> waitForUserAction()\r\n\r\nThe text now is splitted on many lines and no one characters gets lost. Of course, the too long single word is splitted\r\nby an ugly barbarian at some random character (depending on the rect size, font, and so on).\r\n\r\nAnother possible value for the 'line_length_criteria' attribute is \"overflow\" (dangerous! See below).\r\n\r\n >>> ktext.line_length_criteria = \"overflow\"\r\n >>> ktext.invalidate()\r\n >>> ktext.draw(surface)\r\n >>> blitSurface()\r\n >>> waitForUserAction()\r\n\r\nAs you can see, the too long word now is alone on a text line (like before) but the word itself isn't modified:\r\nsimply the text is draw outside the Rect defined (and also the Surface...).\r\n\r\nText too long for the Rect height\r\n---------------------------------\r\n\r\nTo test the vertical limit, I change the font used by the example, so I can use less text.\r\n\r\n >>> ktext.font = pygame.font.Font(None, 42)\r\n >>> ktext.invalidate()\r\n >>> ktext.draw(surface)\r\n >>> blitSurface()\r\n >>> waitForUserAction()\r\n\r\nFirst of all note that the previous test has not cleaned correctly the window. This because using the \"overflow\"\r\ncriteria for the 'line_length_criteria' attribute can lead to text drawn outside the area that the\r\nKTextSurfaceWriter normally refresh.\r\nYou are on your own!\r\n\r\nLets go back to the new example.\r\nAs you can also note there's not limit to the text height rigth now. So if you display too much text in the Rect, this simply\r\nwill pass over the bottom constraint.\r\n\r\nThis is the default behaviour that you can change modifying the 'page_length_criteria' attribute. The default value is\r\n\"overflow\", as you see above (again: can be dangerous).\r\nWe can change this to \"cut\" and we will se a different result.\r\n\r\n >>> ktext.page_length_criteria = \"cut\"\r\n >>> ktext.invalidate()\r\n >>> ktext.draw(surface)\r\n >>> blitSurface()\r\n >>> waitForUserAction()\r\n\r\nYou haven't seen difference? This is not true... The problem is always related to our bad test above: we blit outside the\r\ncontrolled area of the KTextSurfaceWriter instance! And the invalidate method seems doing nothing because it can't clean\r\nour dirty work.\r\n\r\nLets clean the surface a little, before going on!\r\n\r\n >>> surface.fill( (255,255,255,255) )\r\n \r\n\r\nNow we can try again.\r\n\r\n >>> ktext.invalidate()\r\n >>> ktext.draw(surface)\r\n >>> blitSurface()\r\n >>> waitForUserAction()\r\n\r\nConlusion\r\n---------\r\n\r\nAs you can see, the library does a single thing, but try to do it well!\r\n\r\nComments, issues found and feedbacks are welcome, `contact me`__!\r\n\r\n__ mailto:lucafbb@gmail.com\r\n\r\n >>> pygame.quit()\r\n\r\nTODO\r\n====\r\n\r\n * A way to scroll a too (vertically) long text.\r\n * Split PyGame logic fron pure text algorithms.\r\n\r\nSubversion and other\r\n====================\r\n\r\nThe SVN repository is hosted at the `Keul's Python Libraries`__\r\n\r\n__ https://sourceforge.net/projects/kpython-utils/\r\n\r\n\r\nChangelog\r\n=========\r\n\r\n0.1.0\r\n-----\r\n\r\n * First release.", "description_content_type": null, "docs_url": null, "download_url": "UNKNOWN", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/keul/KTextSurfaceWriter", "keywords": "python pygame text surface ktextsurfacewriter library", "license": "GPL", "maintainer": "", "maintainer_email": "", "name": "KTextSurfaceWriter", "package_url": "https://pypi.org/project/KTextSurfaceWriter/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/KTextSurfaceWriter/", "project_urls": { "Download": "UNKNOWN", "Homepage": "https://github.com/keul/KTextSurfaceWriter" }, "release_url": "https://pypi.org/project/KTextSurfaceWriter/0.1.0/", "requires_dist": null, "requires_python": null, "summary": "A PyGame addon for display text over surface with many dimension bounds", "version": "0.1.0" }, "last_serial": 1177769, "releases": { "0.1.0": [ { "comment_text": "", "digests": { "md5": "eebebd61ad2ae5d4f26cbf32991ab63c", "sha256": "dff76153e92e8580aec44534bf27dfa58c8ddd483dbf690227dcbb587649a2c2" }, "downloads": -1, "filename": "KTextSurfaceWriter-0.1.0.tar.gz", "has_sig": false, "md5_digest": "eebebd61ad2ae5d4f26cbf32991ab63c", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 8243, "upload_time": "2009-01-03T12:11:03", "url": "https://files.pythonhosted.org/packages/c6/23/90fddb820d636c62ba0d988ca72131d7fc58a0b0393e42ae0d1127bd6a3f/KTextSurfaceWriter-0.1.0.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "eebebd61ad2ae5d4f26cbf32991ab63c", "sha256": "dff76153e92e8580aec44534bf27dfa58c8ddd483dbf690227dcbb587649a2c2" }, "downloads": -1, "filename": "KTextSurfaceWriter-0.1.0.tar.gz", "has_sig": false, "md5_digest": "eebebd61ad2ae5d4f26cbf32991ab63c", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 8243, "upload_time": "2009-01-03T12:11:03", "url": "https://files.pythonhosted.org/packages/c6/23/90fddb820d636c62ba0d988ca72131d7fc58a0b0393e42ae0d1127bd6a3f/KTextSurfaceWriter-0.1.0.tar.gz" } ] }