文本表面写入器 0.1.0

初始化所有pygame组件

让我们开始加载KTextSurfaceWrite类

>>> from ktextsurfacewriter import KTextSurfaceWriter

现在初始化我们需要的最小pygame环境。

>>> import pygame
>>> from pygame.locals import *
>>> import pygame.font
>>> pygame.font.init()
>>> screen = pygame.display.set_mode((640,480), 0, 32)

为了让事情变得更复杂，我不会直接在屏幕上绘制，而是在一个我可以绘制的地方得到一个表面。

>>> surface = pygame.Surface( (400,400), flags=SRCALPHA, depth=32 )
>>> surface.fill( (255,255,255,255) )
<rect(0, 0, 400, 400)>

现在我们可以在屏幕上绘制这个表面。我们将重复这个步骤几次，所以最好创建一个虚拟函数（这些函数在这个测试环境中之外没有用）。

>>> def blitSurface():
...     screen.blit(surface, (50,50) )
...     pygame.display.update()

所以我们第一次调用它。

>>> blitSurface()

这是一个图形测试，因此我们需要延迟绘制，并允许用户查看结果后再继续。在继续之前，我们等待用户输入。为此，我们创建了一个第二个愚蠢的函数，稍后我们会经常调用它。

>>> def waitForUserAction():
...     while True:
...
...         for event in pygame.event.get():
...             if event.type == QUIT:
...                 import sys
...                 sys.exit(0)
...             if event.type==KEYDOWN:
...                 return

好的，我们第一次调用它。

>>> waitForUserAction()

简单的文本绘制

我们准备创建类的实例。__init__ 方法需要一个 pygame.Rect。这个 Rect 将是我们的边界，文本将保持在这个边界内。

>>> text_rect = pygame.Rect( (10,10),(350,350) )
>>> text_rect
<rect(10, 10, 350, 350)>

这意味着文本将从左上角的 x,y 坐标（10,10）开始显示在表面上。文本的宽度和高度也不会超过 350 像素。

现在我们将文本加载到 KTextSurfaceWriter 中，但在这样做之前（显然）我们需要实例。

>>> ktext = KTextSurfaceWriter(text_rect)

现在文本。

>>> import example_texts
>>> ktext.text = example_texts.EXAMPLE_TEXT_1

现在一些颜色以获得更好的显示效果

>>> ktext.color = (0,0,0,255)
>>> ktext.fillcolor = (155,155,155,255)

我们将填充颜色改为灰色，因为这样更容易看出我们在黑色屏幕上绘制了一个白色表面，并在比表面本身短的矩形内绘制了文本。

好吧，别说话了，让我们显示它！

>>> ktext.draw(surface)
>>> blitSurface()
>>> waitForUserAction()

简单（但更长）的文本绘制

上面的文本非常短，所以我们现在没有测试 KTextSurfaceWriter 的所有功能。让我们用一个更长的试试…

>>> ktext.text = example_texts.EXAMPLE_TEXT_2

现在我们可以立即测试这个新文本。

>>> ktext.draw(surface)
>>> blitSurface()
>>> waitForUserAction()

有什么变化？即使 EXAMPLE_TEXT_2 字符串没有在多行中分割，显示的文本也永远不会超出我们使用的 pygame.Rect 实例的限制！

那么，如果文本已经分割成多行呢？

>>> ktext.text = example_texts.EXAMPLE_TEXT_3
>>> ktext.draw(surface)
>>> blitSurface()
>>> waitForUserAction()

显然，文本中的换行符被保留。我们还可以考虑进行一点缩进，以便为新行（因为它们被插入到文本中）和自动生成的较长的文本创建不同的渲染效果。

>>> ktext.justify_chars = 3

如果我们再次绘制，我们会得到没有区别。为了性能需求，KTextSurfaceWriter.draw 方法不会每次都评估文本和字体图形内容，而是缓存结果。当你更改文本时，也会自动使这个缓存无效，但如果你没有更改它，你总是可以手动更改它。

>>> ktext.invalidate()

好吧，现在你会看到区别。

>>> ktext.draw(surface)
>>> blitSurface()
>>> waitForUserAction()

单行文本太长

我们想在矩形内绘制文本，但这并不总是可能的，即使我们使用一个像整个表面一样大的 pygame.Rect，也总是有可能传入的文本太长。

在这种情况下会发生什么？

>>> ktext.text = example_texts.EXAMPLE_TEXT_4
>>> ktext.draw(surface)
>>> blitSurface()
>>> waitForUserAction()

默认行为是在可能的最大长度处切断单词。这是因为如果没有明确说明，KTextSurfaceWriter 实例使用一个称为“cut”的标准。你可以将其更改为另一个值。

>>> ktext.line_length_criteria = "split"

然后如果我们重复测试，我们得到新的行为。

>>> ktext.invalidate()
>>> ktext.draw(surface)
>>> blitSurface()
>>> waitForUserAction()

现在文本被分割成多行，没有任何字符丢失。当然，太长的单个单词会在某些随机字符（取决于矩形大小、字体等）处被丑陋地分割。

‘line_length_criteria’ 属性的另一个可能值是“overflow”（危险！见下文）。

>>> ktext.line_length_criteria = "overflow"
>>> ktext.invalidate()
>>> ktext.draw(surface)
>>> blitSurface()
>>> waitForUserAction()

正如你所看到的，太长的单词现在单独在文本行上（就像以前一样），但单词本身并没有被修改：简单地将文本绘制在定义的 Rect 之外（以及 Surface…）。

矩形高度不足以容纳文本

为了测试垂直限制，我改变了示例中使用的字体，这样我就可以使用更少的文本。

>>> ktext.font = pygame.font.Font(None, 42)
>>> ktext.invalidate()
>>> ktext.draw(surface)
>>> blitSurface()
>>> waitForUserAction()

首先请注意，之前的测试没有正确清理窗口。这是因为使用“overflow”标准为“line_length_criteria”属性可能会导致文本绘制到KTextSurfaceWriter通常刷新的区域之外。你自己看着办吧！

让我们回到新的例子。您也可以注意到，文本高度目前没有限制。因此，如果在Rect中显示太多文本，它将简单地越过底部的约束。

这是可以通过修改“page_length_criteria”属性来更改的默认行为。默认值是“overflow”，如上所述（再次提醒：可能很危险）。我们可以将其更改为“cut”，并会看到不同的结果。

>>> ktext.page_length_criteria = "cut"
>>> ktext.invalidate()
>>> ktext.draw(surface)
>>> blitSurface()
>>> waitForUserAction()

您没有看到区别？这不是真的……问题总是与我们的不良测试有关：我们在KTextSurfaceWriter实例的控制区域之外绘制！无效化方法似乎没有作用，因为它无法清理我们的脏工作。

在继续之前，让我们稍微清理一下表面！

>>> surface.fill( (255,255,255,255) )
<rect(0, 0, 400, 400)>

现在我们可以再试一次。

>>> ktext.invalidate()
>>> ktext.draw(surface)
>>> blitSurface()
>>> waitForUserAction()

结论

如您所见，该库只做一件事，但试图做好！

欢迎评论、发现的问题和反馈，联系我！

>>> pygame.quit()